mirror of
https://github.com/grafana/grafana.git
synced 2025-07-28 02:52:13 +08:00
537 lines
11 KiB
Markdown
537 lines
11 KiB
Markdown
---
|
|
aliases:
|
|
- ../../http_api/serviceaccount/
|
|
canonical: /docs/grafana/latest/developers/http_api/serviceaccount/
|
|
description: Grafana service account HTTP API
|
|
keywords:
|
|
- grafana
|
|
- http
|
|
- documentation
|
|
- api
|
|
- serviceaccount
|
|
labels:
|
|
products:
|
|
- enterprise
|
|
- oss
|
|
title: Service account HTTP API
|
|
---
|
|
|
|
# Service account API
|
|
|
|
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions](/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes/) for more information.
|
|
> For Grafana Cloud instances, please use a Bearer token to authenticate. The examples within this section reference Basic authentication which is for On-Prem Grafana instances.
|
|
|
|
## Search service accounts with Paging
|
|
|
|
`GET /api/serviceaccounts/search?perpage=10&page=1&query=myserviceaccount`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| -------------------- | ----- |
|
|
| serviceaccounts:read | n/a |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/serviceaccounts/search?perpage=10&page=1&query=mygraf HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
Default value for the `perpage` parameter is `1000` and for the `page` parameter is `1`. The `totalCount` field in the response can be used for pagination of the user list E.g. if `totalCount` is equal to 100 users and the `perpage` parameter is set to 10 then there are 10 pages of users. The `query` parameter is optional and it will return results where the query value is contained in one of the `name`. Query values with spaces need to be URL encoded e.g. `query=Jane%20Doe`.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
{
|
|
```
|
|
|
|
## Create service account
|
|
|
|
`POST /api/serviceaccounts`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------------------- | ----- |
|
|
| serviceaccounts:create | n/a |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/serviceaccounts HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 201
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Fixed and custom roles can be set on service accounts using the [RBAC HTTP API](/docs/grafana/latest/developers/http_api/access_control/#set-user-role-assignments).
|
|
|
|
## Get a service account by ID
|
|
|
|
`GET /api/serviceaccounts/:id`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| -------------------- | --------------------- |
|
|
| serviceaccounts:read | serviceaccounts:id:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/serviceaccounts/1 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Update service account
|
|
|
|
`PATCH /api/serviceaccounts/:id`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| --------------------- | --------------------- |
|
|
| serviceaccounts:write | serviceaccounts:id:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
PATCH /api/serviceaccounts/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
Fixed and custom roles can be set on service accounts using the [RBAC HTTP API](/docs/grafana/latest/developers/http_api/access_control/#set-user-role-assignments).
|
|
|
|
## Delete service account
|
|
|
|
`DELETE /api/serviceaccounts/:id`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------------------- | --------------------- |
|
|
| serviceaccounts:delete | serviceaccounts:id:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/serviceaccounts/2 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## Migrate API keys to service accounts
|
|
|
|
`POST /api/serviceaccounts/migrate`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| --------------------- | ------------------ |
|
|
| serviceaccounts:write | serviceaccounts:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/serviceaccounts/migrate HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Migrate API key to service account
|
|
|
|
`POST /api/serviceaccounts/migrate/:keyId`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| --------------------- | ------------------ |
|
|
| serviceaccounts:write | serviceaccounts:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/serviceaccounts/migrate/4 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Get API key to service account migration status
|
|
|
|
`GET /api/serviceaccounts/migrationstatus`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| -------------------- | ------------------ |
|
|
| serviceaccounts:read | serviceaccounts:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/serviceaccounts/migrationstatus HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Hide the API keys tab
|
|
|
|
`GET /api/serviceaccounts/hideApiKeys`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| --------------------- | ------------------ |
|
|
| serviceaccounts:write | serviceaccounts:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/serviceaccounts/hideApiKeys HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Get service account tokens
|
|
|
|
`GET /api/serviceaccounts/:id/tokens`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| -------------------- | --------------------- |
|
|
| serviceaccounts:read | serviceaccounts:id:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
GET /api/serviceaccounts/2/tokens HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Create service account tokens
|
|
|
|
`POST /api/serviceaccounts/:id/tokens`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| --------------------- | --------------------- |
|
|
| serviceaccounts:write | serviceaccounts:id:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
POST /api/serviceaccounts/2/tokens HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
|
|
```
|
|
|
|
Default value for the `secondsToLive` is 0, which means that the service account token will never expire.
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Delete service account tokens
|
|
|
|
`DELETE /api/serviceaccounts/:id/tokens/:tokenId`
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| --------------------- | --------------------- |
|
|
| serviceaccounts:write | serviceaccounts:id:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/serviceaccounts/2/tokens/1 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|
|
|
|
## Revert service account token to API key
|
|
|
|
`DELETE /api/serviceaccounts/:serviceAccountId/revert/:keyId`
|
|
|
|
This operation will delete the service account and create a legacy API Key for the given `keyId`.
|
|
|
|
**Required permissions**
|
|
|
|
See note in the [introduction](#service-account-api) for an explanation.
|
|
|
|
| Action | Scope |
|
|
| ---------------------- | --------------------- |
|
|
| serviceaccounts:delete | serviceaccounts:id:\* |
|
|
|
|
**Example Request**:
|
|
|
|
```http
|
|
DELETE /api/serviceaccounts/1/revert/glsa_VVQjot0nijQ59lun6pMZRtsdBXxnFQ9M_77c34a79 HTTP/1.1
|
|
Accept: application/json
|
|
Content-Type: application/json
|
|
Authorization: Basic YWRtaW46YWRtaW4=
|
|
```
|
|
|
|
**Example Response**:
|
|
|
|
```http
|
|
HTTP/1.1 200
|
|
Content-Type: application/json
|
|
|
|
```
|