Service accounts API
5 endpoints. Request and response schemas are described on the schemas page; the other tags are listed in the API index.
Endpoints
GET /api/v1/service-accounts
List service accounts
List service accounts, by name (admin only).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | no | Minimum: 1. |
per_page | query | integer | no | Minimum: 1. Maximum: 200. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Service accounts | application/json: object |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
Fields of the 200 response (application/json):
| Field | Type | Required | Description |
|---|---|---|---|
data | array of ServiceAccount | no | - |
page | integer | no | - |
per_page | integer | no | - |
total | integer | no | - |
POST /api/v1/service-accounts
Create service account
Create a service account: a named non-human principal for automation (admin only). It can hold project roles, group memberships and permission assignments like a user, and own API tokens through /api/v1/users/{id}/tokens, but it cannot sign in.
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
description | string | no | Maximum length: 255. |
disabled | boolean | no | - |
name | string | yes | 3-64 letters, digits, dash or underscore; unique among users and service accounts; cannot be changed. |
Responses
| Status | Description | Body |
|---|---|---|
201 | Service account created | application/json: ServiceAccount |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
409 | A user or service account with this name exists | application/json: Error |
GET /api/v1/service-accounts/{id}
Get service account
Get one service account (admin only).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Service account | application/json: ServiceAccount |
403 | Admin access required | - |
404 | Service account not found | - |
PATCH /api/v1/service-accounts/{id}
Update service account
Change the description or disable or re-enable a service account (admin only). A disabled account's tokens, including those already issued, authenticate nothing.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Request body (required)
application/json: object
| Field | Type | Required | Description |
|---|---|---|---|
description | string | no | Maximum length: 255. |
disabled | boolean | no | - |
Responses
| Status | Description | Body |
|---|---|---|
200 | Service account updated | application/json: ServiceAccount |
400 | Invalid request | application/json: Error |
403 | Admin access required | - |
404 | Service account not found | - |
DELETE /api/v1/service-accounts/{id}
Delete service account
Delete a service account with its tokens, group memberships, project roles, permission assignments and trust policies (admin only).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string (uuid) | yes | - |
Responses
| Status | Description | Body |
|---|---|---|
204 | Service account deleted | - |
403 | Admin access required | - |
404 | Service account not found | - |