ContextQMD
Back to Grafana

Service account HTTP API

docs/sources/developer-resources/api-reference/http-api/api-legacy/serviceaccount.md

13.0.17.9 KB
Original Source

Service account API

{{< docs/shared lookup="developers/deprecated-apis.md" source="grafana" version="<GRAFANA_VERSION>" >}}

If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to Role-based access control permissions 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 for an explanation.

ActionScope
serviceaccounts:readn/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
{
	"totalCount": 2,
	"serviceAccounts": [
		{
			"id": 1,
			"name": "grafana",
			"login": "sa-grafana",
			"orgId": 1,
			"isDisabled": false,
			"role": "Viewer",
			"tokens": 0,
			"avatarUrl": "/avatar/85ec38023d90823d3e5b43ef35646af9",
			"accessControl": {
				"serviceaccounts:delete": true,
				"serviceaccounts:read": true,
				"serviceaccounts:write": true
			}
		},
		{
			"id": 2,
			"name": "test",
			"login": "sa-test",
			"orgId": 1,
			"isDisabled": false,
			"role": "Viewer",
			"tokens": 0,
			"avatarUrl": "/avatar/8ea890a677d6a223c591a1beea6ea9d2",
			"accessControl": {
				"serviceaccounts:delete": true,
				"serviceaccounts:read": true,
				"serviceaccounts:write": true
			}
		}
	],
	"page": 1,
	"perPage": 10
}

Create service account

POST /api/serviceaccounts

Required permissions

See note in the introduction for an explanation.

ActionScope
serviceaccounts:createn/a

Example Request:

http
POST /api/serviceaccounts HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "name": "grafana",
  "role": "Viewer",
  "isDisabled": false
}

Example Response:

http
HTTP/1.1 201
Content-Type: application/json

{
	"id": 1,
	"name": "test",
	"login": "sa-test",
	"orgId": 1,
	"isDisabled": false,
	"createdAt": "2022-03-21T14:35:33Z",
	"updatedAt": "2022-03-21T14:35:33Z",
	"avatarUrl": "/avatar/8ea890a677d6a223c591a1beea6ea9d2",
	"role": "Viewer",
	"teams": []
}

Fixed and custom roles can be set on service accounts using the RBAC HTTP API.

Get a service account by ID

GET /api/serviceaccounts/:id

Required permissions

See note in the introduction for an explanation.

ActionScope
serviceaccounts:readserviceaccounts: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

{
	"id": 1,
	"name": "test",
	"login": "sa-test",
	"orgId": 1,
	"isDisabled": false,
	"createdAt": "2022-03-21T14:35:33Z",
	"updatedAt": "2022-03-21T14:35:33Z",
	"avatarUrl": "/avatar/8ea890a677d6a223c591a1beea6ea9d2",
	"role": "Viewer",
	"teams": []
}

Update service account

PATCH /api/serviceaccounts/:id

Required permissions

See note in the introduction for an explanation.

ActionScope
serviceaccounts:writeserviceaccounts:id:*

Example Request:

http
PATCH /api/serviceaccounts/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=

{
  "name": "test",
	"role": "Editor"
}

Example Response:

http
HTTP/1.1 200
Content-Type: application/json

{
	"id": 2,
	"name": "test",
	"login": "sa-grafana",
	"orgId": 1,
	"isDisabled": false,
	"createdAt": "2022-03-21T14:35:44Z",
	"updatedAt": "2022-03-21T14:35:44Z",
	"avatarUrl": "/avatar/8ea890a677d6a223c591a1beea6ea9d2",
	"role": "Editor",
	"teams": []
}

Fixed and custom roles can be set on service accounts using the RBAC HTTP API.

Delete service account

DELETE /api/serviceaccounts/:id

Required permissions

See note in the introduction for an explanation.

ActionScope
serviceaccounts:deleteserviceaccounts: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

{
	"message": "Service account deleted"
}

Get service account tokens

GET /api/serviceaccounts/:id/tokens

Required permissions

See note in the introduction for an explanation.

ActionScope
serviceaccounts:readserviceaccounts: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 for an explanation.

ActionScope
serviceaccounts:writeserviceaccounts: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 for an explanation.

ActionScope
serviceaccounts:writeserviceaccounts: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"
}