grafana/docs/sources/developers/http_api/serviceaccount.md

---
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]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.

## Search service accounts with Paging

`GET /api/serviceaccounts/search?perpage=10&page=1&query=myserviceaccount`

**Required permissions**

See note in the [introduction]({{< ref "#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]({{< ref "#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

```

## Get a service account by ID

`GET /api/serviceaccounts/:id`

**Required permissions**

See note in the [introduction]({{< ref "#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]({{< ref "#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

```

## Delete service account

`DELETE /api/serviceaccounts/:id`

**Required permissions**

See note in the [introduction]({{< ref "#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]({{< ref "#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]({{< ref "#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]({{< ref "#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]({{< ref "#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]({{< ref "#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]({{< ref "#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=

```

**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]({{< ref "#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]({{< ref "#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

```