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	The ID or URL-encoded path of the group
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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 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	The ID or URL-encoded path of the group

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 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	The ID or URL-encoded path of the group
`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 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	The ID or URL-encoded path of the group
`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 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	The ID or URL-encoded path of the group
`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`	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	The ID or URL-encoded path of the group
`revoked` Query	Boolean	Filter tokens where revoked state matches parameter Example: `false`
`state` Query	String	Filter tokens which are either active or not Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Filter tokens which were created before given datetime Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Filter tokens which were created after given datetime Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Filter tokens which were used before given datetime Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Filter tokens which were used after given datetime Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Filter tokens which expire before given datetime Example: `2022-01-01`
`expires_after` Query	String (date)	Filter tokens which expire after given datetime Example: `2021-01-01`
`search` Query	String	Filters tokens by name Example: `token`
`sort` Query	String	Sort tokens Example: `created_at_desc`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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 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	The ID or URL-encoded path of the group
`user_id` Path, required	Integer	The ID of the service account

Request body (application/json)

Property	Type	Description
`description`	String	The description of the access token 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	The 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 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	The ID or URL-encoded path of the group
`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 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	The ID or URL-encoded path of the group
`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 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	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	Filter tokens where revoked state matches parameter Example: `false`
`state` Query	String	Filter tokens which are either active or not Allowed values: `active`, `inactive` Example: `active`
`created_before` Query	String (date-time)	Filter tokens which were created before given datetime Example: `2022-01-01T00:00:00Z`
`created_after` Query	String (date-time)	Filter tokens which were created after given datetime Example: `2021-01-01T00:00:00Z`
`last_used_before` Query	String (date-time)	Filter tokens which were used before given datetime Example: `2021-01-01T00:00:00Z`
`last_used_after` Query	String (date-time)	Filter tokens which were used after given datetime Example: `2022-01-01T00:00:00Z`
`expires_before` Query	String (date)	Filter tokens which expire before given datetime Example: `2022-01-01`
`expires_after` Query	String (date)	Filter tokens which expire after given datetime Example: `2021-01-01`
`search` Query	String	Filters tokens by name Example: `token`
`sort` Query	String	Sort tokens Example: `created_at_desc`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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	The description of the access token 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	The 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	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items 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
`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
`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`
`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