[release-12.3.0] Restructure As code and developer resources (#113969)
Co-authored-by: Roberto Jiménez Sánchez <roberto.jimenez@grafana.com> Co-authored-by: Anna Urbiztondo <anna.urbiztondo@grafana.com>
This commit is contained in:
Jack Baldry
GitHub
@@ -0,0 +1,376 @@
|
||||
---
|
||||
aliases:
|
||||
- ../../../http_api/serviceaccount/ # /docs/grafana/next/http_api/serviceaccount/
|
||||
- ../../../developers/http_api/serviceaccount/ # /docs/grafana/next/developers/http_api/serviceaccount/
|
||||
canonical: https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/serviceaccount/
|
||||
description: Grafana service account HTTP API
|
||||
keywords:
|
||||
- grafana
|
||||
- http
|
||||
- documentation
|
||||
- api
|
||||
- serviceaccount
|
||||
labels:
|
||||
products:
|
||||
- enterprise
|
||||
- oss
|
||||
- cloud
|
||||
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
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"name": "grafana",
|
||||
"role": "Viewer",
|
||||
"created": "2022-03-23T10:31:02Z",
|
||||
"expiration": null,
|
||||
"secondsUntilExpiration": 0,
|
||||
"hasExpired": false
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## 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=
|
||||
|
||||
{
|
||||
"name": "grafana",
|
||||
"secondsToLive": 604800
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
|
||||
{
|
||||
"id": 7,
|
||||
"name": "grafana",
|
||||
"key": "eyJrIjoiVjFxTHZ6dGdPSjg5Um92MjN1RlhjMkNqYkZUbm9jYkwiLCJuIjoiZ3JhZmFuYSIsImlkIjoxfQ=="
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
{
|
||||
"message": "API key deleted"
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user