IntenseWebs/grafana
3
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-02-25 18:55:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

Docs: RBAC GA (#49062)

Browse Source
This commit is contained in:
Karl Persson
2022-05-20 21:48:52 +02:00
committed by GitHub
parent b3b650be1f
commit 0cbe4fe661
34 changed files with 350 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/sources/developers/http_api/access_control.md
View File

@@ -9,10 +9,9 @@ title = "RBAC HTTP API"
> Role-based access control API is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../../enterprise" >}}).
The API can be used to create, update, get and list roles, and create or remove assignments.
To use the API, you would need to [enable role-based access control]({{< relref "../../enterprise/access-control/_index.md#enable-role-based-access-control" >}}).
The API can be used to create, update, delete, get, and list roles.
The API does not currently work with an API Token. So in order to use these API endpoints you will have to use [Basic auth]({{< relref "auth#basic-auth" >}}).
To check which basic or fixed roles have the required permissions, refer to [RBAC role definitions]({{< ref "../../enterprise/access-control/rbac-fixed-basic-role-definitions.md" >}}).
## Get status

25
docs/sources/developers/http_api/admin.md
View File

@@ -11,8 +11,7 @@ The Admin HTTP API does not currently work with an API Token. API Tokens are cur
the permission of server admin, only users can be given that permission. So in order to use these API calls you will have to use Basic Auth and the Grafana user
must have the Grafana Admin permission. (The default admin user is called `admin` and has permission to use this API.)
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
> Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Fetch settings
@@ -20,7 +19,7 @@ must have the Grafana Admin permission. (The default admin user is called `admin
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
@@ -192,7 +191,7 @@ Updates / removes and reloads database settings. You must provide either `update
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
Change password for a specific user.
**Required permissions**
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
@@ -246,7 +245,7 @@ Status codes:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Delete global User
@@ -328,7 +327,7 @@ Content-Type: application/json
GET /api/admin/users/1/auth-tokens HTTP/1.1
Accept: application/json
Content-Type: application/json
```
```
**Example Response**:
@@ -370,7 +369,7 @@ Content-Type: application/json
HTTP/1.1 200
Content-Type: application/json
```
```
## Logout User
@@ -403,7 +402,7 @@ Content-Type: application/json
HTTP/1.1 200
Content-Type: application/json
```
```
## Reload provisioning configurations
@@ -436,7 +435,7 @@ Content-Type: application/json
| provisioning:reload | provisioners:notifications | notifications |
**Example Request**:
```http
POST /api/admin/provisioning/dashboards/reload HTTP/1.1
Accept: application/json
@@ -504,7 +503,7 @@ Return a list of all auth tokens (devices) that the user currently have logged i
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
@@ -563,7 +562,7 @@ and will be required to authenticate again upon next activity.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
@@ -603,7 +602,7 @@ and will be required to authenticate again upon next activity.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
@@ -648,7 +647,7 @@ polling for changes in dashboard files and then restart it with new configuratio
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.

17
docs/sources/developers/http_api/annotations.md
View File

@@ -9,14 +9,13 @@ title = "Annotations HTTP API "
This is the API documentation for the new Grafana Annotations feature released in Grafana 4.6. Annotations are saved in the Grafana database (sqlite, mysql or postgres). Annotations can be organization annotations that can be shown on any dashboard by configuring an annotation data source - they are filtered by tags. Or they can be tied to a panel on a dashboard and are then only shown on that panel.
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by role-based access control permissions.
> Refer to specific endpoints to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Find Annotations
`GET /api/annotations?from=1506676478816&to=1507281278816&tags=tag1&tags=tag2&limit=100`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
@@ -105,7 +104,7 @@ The format for `time` and `timeEnd` should be epoch numbers in millisecond resol
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
| Action | Scope |
| Action | Scope |
| ------------------ | ----------------------------- |
| annotations:create | annotations:type:organization |
@@ -153,7 +152,7 @@ format (string with multiple tags being separated by a space).
**Example Response**:
```http
HTTP/1.1 200
HTTP/1.1 200
Content-Type: application/json
```
@@ -194,7 +193,7 @@ Content-Type: application/json
```
## Delete Annotation By Id
## Delete Annotation By Id
`DELETE /api/annotations/:id`
@@ -239,7 +238,7 @@ Updates one or more properties of an annotation that matches the specified id.
| ---------------- | ----- |
| annotations:read | N/A |
**Example Request**:
**Example Request**:
```http
GET /api/annotations/tags?tag=out HTTP/1.1
@@ -278,7 +277,7 @@ Content-Type: application/json
Deletes the annotation that matches the specified id.
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.
@@ -312,7 +311,7 @@ Content-Type: application/json
Find all the event tags created in the annotations.
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#annotations-api" >}}) for an explanation.

28
docs/sources/developers/http_api/auth.md
View File

@@ -7,9 +7,11 @@ title = "Authentication HTTP API "
# Authentication API
> If you are running Grafana Enterprise, for some endpoints you would need to have relevant permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Tokens
Currently you can authenticate via an `API Token` or via a `Session cookie` (acquired using regular login or OAuth).
Currently, you can authenticate via an `API Token` or via a `Session cookie` (acquired using regular login or OAuth).
## X-Grafana-Org-Id Header
@@ -76,6 +78,14 @@ curl example:
See note in the [introduction]({{< ref "#authentication-api" >}}) for an explanation.
| Action | Scope |
| -------------- | ----------- |
| `apikeys:read` | `apikeys:*` |
**Example Request**:
```http
GET /api/auth/keys HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
@@ -114,6 +124,14 @@ Content-Type: application/json
```
JSON Body schema:
- **name** – The key name
- **role** – Sets the access level/Grafana Role for the key. Can be one of the following values: `Viewer`, `Editor` or `Admin`.
- **secondsToLive** – Sets the key expiration in seconds. It is optional. If it is a positive number an expiration date for the key is set. If it is null, zero or is omitted completely (unless `api_key_max_seconds_to_live` configuration option is set) the key will never expire.
Error statuses:
- **400** – `api_key_max_seconds_to_live` is set but no `secondsToLive` is specified or `secondsToLive` is greater than this value.
- **500** – The key was unable to be stored in the database.
@@ -153,6 +171,14 @@ Content-Type: application/json
Content-Type: application/json
```
**Required permissions**
See note in the [introduction]({{< ref "#authentication-api" >}}) for an explanation.
| Action | Scope |
| ---------------- | ---------- |
| `apikeys:delete` | apikeys:\* |
**Example Request**:
```http

26
docs/sources/developers/http_api/dashboard.md
View File

@@ -7,6 +7,8 @@ title = "Dashboard HTTP API "
# Dashboard 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 "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Identifier (id) vs unique identifier (uid)
The identifier (id) of a dashboard is an auto-incrementing numeric value and is only unique per Grafana install.
@@ -24,6 +26,14 @@ The uid can have a maximum length of 40 characters.
Creates a new dashboard or updates an existing dashboard. When updating existing dashboards, if you do not define the `folderId` or the `folderUid` property, then the dashboard(s) are moved to the General folder. (You need to define only one property, not both).
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
| Action | Scope |
| ------------------- | ----------- |
| `dashboards:create` | `folders:*` |
**Example Request for new dashboard**:
```http
@@ -272,6 +282,14 @@ In case of title already exists the `status` property will be `name-exists`.
Will return the dashboard given the dashboard unique identifier (uid). Information about the unique identifier of a folder containing the requested dashboard might be found in the metadata.
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
| Action | Scope |
| ----------------- | -------------- |
| `dashboards:read` | `dashboards:*` |
**Example Request**:
```http
@@ -320,6 +338,14 @@ Status Codes:
Will delete the dashboard given the specified unique identifier (uid).
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-api" >}}) for an explanation.
| Action | Scope |
| ------------------- | ----------------------------- |
| `dashboards:delete` | `dashboards:*`<br>`folders:*` |
**Example Request**:
```http

34
docs/sources/developers/http_api/dashboard_permissions.md
View File

@@ -17,12 +17,22 @@ The permission levels for the permission field:
- 2 = Edit
- 4 = Admin
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Get permissions for a dashboard
`GET /api/dashboards/uid/:uid/permissions`
Gets all existing permissions for the dashboard with the given `uid`.
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-permission-api" >}}) for an explanation.
| Action | Scope |
| ----------------------------- | ------------------------------------- |
| `dashboards.permissions:read` | `dashboards:uid:*`<br>`folders:uid:*` |
**Example request**:
```http
@@ -94,6 +104,14 @@ Status Codes:
JSON body schema:
- **items** - The permission items to add/update. Items that are omitted from the list will be removed.
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35
```
@@ -153,6 +171,14 @@ Status Codes:
Updates permissions for a dashboard. This operation will remove existing permissions if they're not included in the request.
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-permission-api" >}}) for an explanation.
| Action | Scope |
| ------------------------------ | ----------------------------- |
| `dashboards.permissions:write` | `dashboards:*`<br>`folders:*` |
**Example request**:
```http
@@ -226,6 +252,14 @@ Status Codes:
Updates permissions for a dashboard. This operation will remove existing permissions if they're not included in the request.
**Required permissions**
See note in the [introduction]({{< ref "#dashboard-permission-api" >}}) for an explanation.
| Action | Scope |
| ------------------------------ | ----------------------------- |
| `dashboards.permissions:write` | `dashboards:*`<br>`folders:*` |
**Example request**:
```http

23
docs/sources/developers/http_api/data_source.md
View File

@@ -7,14 +7,13 @@ title = "Data source HTTP API "
# Data source API
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
> Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Get all data sources
`GET /api/datasources`
### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#data-source-api" >}}) for an explanation.
@@ -70,7 +69,7 @@ Content-Type: application/json
HTTP/1.1 200
Content-Type: application/json
```
```
## Get a single data source by UID
@@ -126,7 +125,7 @@ Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
**Example Response**:
```http
HTTP/1.1 200
@@ -182,7 +181,7 @@ Content-Type: application/json
**Example Graphite Request**:
```http
POST /api/datasources HTTP/1.1
POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
@@ -238,7 +237,7 @@ Content-Type: application/json
| Action | Scope |
| ----------------- | ---------------------------------------------------------------------------- |
| datasources:write | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
### Examples
**Example Request**:
@@ -272,7 +271,7 @@ Content-Type: application/json
| Action | Scope |
| ------------------ | ---------------------------------------------------------------------------- |
| datasources:delete | datasources:\*<br>datasources:id:\*<br>datasources:id:1 (single data source) |
### Examples
**Example Request**:
@@ -420,7 +419,7 @@ Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
Makes a call to the resources endpoint of data source identified by the given `dashboardId`.
### Examples
### Examples
**Example Request**:
@@ -500,7 +499,7 @@ Content-Type: application/json
"results": {
"A": {
"frames": [
{
{
"schema": {
"refId": "A",
"fields": [
@@ -532,7 +531,7 @@ Content-Type: application/json
}
}
}
```
```
#### Status codes
@@ -567,7 +566,7 @@ Content-Type: application/json
```
JSON Body schema:
JSON Body schema:
- **from/to** – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`.
- **queries.refId** – Specifies an identifier of the query. Defaults to "A".

13
docs/sources/developers/http_api/datasource_permissions.md
View File

@@ -9,8 +9,7 @@ title = "Datasource Permissions HTTP API "
> The Data Source Permissions is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../../enterprise" >}}).
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
> Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
This API can be used to enable, disable, list, add and remove permissions for a data source.
@@ -26,7 +25,7 @@ The permission levels for the permission field:
Enables permissions for the data source with the given `id`. No one except Org Admins will be able to query the data source until permissions have been added which permit certain users or teams to query the data source.
### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
@@ -71,7 +70,7 @@ Status codes:
Disables permissions for the data source with the given `id`. All existing permissions will be removed and anyone will be able to query the data source.
**Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope |
@@ -116,7 +115,7 @@ Status codes:
**Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.
| Action | Scope |
| ---------------------------- | ---------------------------------------------------------------------------- |
@@ -187,7 +186,7 @@ Status codes:
Content-Length: 35
```
Adds a team permission for the data source with the given `id`.
**Example request:**
@@ -261,7 +260,7 @@ Status codes:
- **401** - Unauthorized
- **403** - Access denied
- **404** - Datasource not found or permission not found
### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#data-source-permissions-api" >}}) for an explanation.

15
docs/sources/developers/http_api/external_group_sync.md
View File

@@ -9,16 +9,15 @@ title = "External Group Sync HTTP API "
> External Group Synchronization is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../../enterprise" >}}).
> If you have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by role-based access control permissions.
> Refer to specific endpoints to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Get External Groups
`GET /api/teams/:teamId/groups`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
See note in the [introduction]({{< ref "#external-group-synchronization-api" >}}) for an explanation.
| Action | Scope |
| ---------------------- | -------- |
@@ -58,9 +57,9 @@ Status Codes:
| Action | Scope |
| ----------------------- | -------- |
| teams.permissions:write | teams:\* |
**Example Request**:
```http
POST /api/teams/1/members HTTP/1.1
Accept: application/json
@@ -100,9 +99,9 @@ Status Codes:
**Example Request**:
```http
DELETE /api/teams/1/groups/cn=editors,ou=groups,dc=grafana,dc=org HTTP/1.1
DELETE /api/teams/1/groups/cn=editors,ou=groups,dc=grafana,dc=org HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```

50
docs/sources/developers/http_api/folder.md
View File

@@ -7,6 +7,8 @@ title = "Folder HTTP API "
# Folder 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 "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Identifier (id) vs unique identifier (uid)
The identifier (id) of a folder is an auto-incrementing numeric value and is only unique per Grafana install.
@@ -26,6 +28,14 @@ that you cannot use this API for retrieving information about the General folder
Returns all folders that the authenticated user has permission to view. You can control the maximum number of folders returned through the `limit` query parameter, the default is 1000. You can also pass the `page` query parameter for fetching folders from a page other than the first one.
**Required permissions**
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
| Action | Scope |
| -------------- | ----------- |
| `folders:read` | `folders:*` |
**Example Request**:
```http
@@ -61,6 +71,14 @@ Content-Type: application/json
```http
GET /api/folders/nErXDvCkzzh HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
@@ -106,6 +124,14 @@ Status Codes:
```http
HTTP/1.1 200
Content-Type: application/json
```
Status Codes:
- **200** – Created
- **400** – Errors (invalid json, missing or invalid fields, etc)
- **401** – Unauthorized
- **403** – Access Denied
- **409** - Folder already exists
@@ -162,6 +188,14 @@ Status Codes:
There can be different reasons for this:
- The folder has been changed by someone else, `status=version-mismatch`
The response body will have the following properties:
```http
HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97
```
## Delete folder
@@ -241,6 +275,14 @@ Deletes an existing folder identified by UID along with all dashboards (and thei
- **200** – Found
- **401** – Unauthorized
- **403** – Access Denied
- **404** – Folder not found
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
| Action | Scope |
| ---------------- | ----------- |
| `folders:delete` | `folders:*` |
**Example Request**:
```http
@@ -277,6 +319,14 @@ Status Codes:
Will return the folder identified by id.
**Required permissions**
See note in the [introduction]({{< ref "#folder-api" >}}) for an explanation.
| Action | Scope |
| -------------- | ----------- |
| `folders:read` | `folders:*` |
**Example Request**:
```http

2
docs/sources/developers/http_api/folder_dashboard_search.md
View File

@@ -11,6 +11,8 @@ title = "Folder/Dashboard Search HTTP API "
`GET /api/search/`
> Note: When using [Role-based access control]({{< relref "../../enterprise/access-control" >}}), search results will contain only dashboards and folders which you have access to.
Query parameters:
- **query** – Search Query

18
docs/sources/developers/http_api/folder_permissions.md
View File

@@ -17,12 +17,22 @@ The permission levels for the permission field:
- 2 = Edit
- 4 = Admin
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Get permissions for a folder
`GET /api/folders/:uid/permissions`
Gets all existing permissions for the folder with the given `uid`.
**Required permissions**
See note in the [introduction]({{< ref "#folder-permission-api" >}}) for an explanation.
| Action | Scope |
| -------------------------- | ----------- |
| `folders.permissions:read` | `folders:*` |
**Example request**:
```http
@@ -94,6 +104,14 @@ Status Codes:
JSON body schema:
- **items** - The permission items to add/update. Items that are omitted from the list will be removed.
**Example response**:
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Content-Length: 35
```
Status Codes:

9
docs/sources/developers/http_api/licensing.md
View File

@@ -9,8 +9,7 @@ title = "Licensing HTTP API "
Licensing is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../../enterprise" >}}).
If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Check license availability
@@ -20,7 +19,7 @@ Refer to specific resources to understand what permissions are required.
Checks if a valid license is available.
### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#enterprise-license-api" >}}) for an explanation.
@@ -60,7 +59,7 @@ Status codes:
Manually ask license issuer for a new token.
**Required permissions**
See note in the [introduction]({{< ref "#enterprise-license-api" >}}) for an explanation.
| Action | Scope |
@@ -120,7 +119,7 @@ Status Codes:
```http
DELETE /api/licensing/token
Accept: application/json
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

37
docs/sources/developers/http_api/org.md
View File

@@ -11,8 +11,7 @@ The Organization HTTP API is divided in two resources, `/api/org` (current organ
and `/api/orgs` (admin organizations). One big difference between these are that
the admin of all organizations API only works with basic authentication, see [Admin Organizations API](#admin-organizations-api) for more information.
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
> Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Current Organization API
@@ -20,7 +19,7 @@ the admin of all organizations API only works with basic authentication, see [Ad
`GET /api/org/`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
@@ -56,7 +55,7 @@ Content-Type: application/json
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
| Action | Scope |
| Action | Scope |
| -------------- | -------- |
| org.users:read | users:\* |
@@ -102,7 +101,7 @@ Accessible to users with org admin role, admin in any folder or admin of any tea
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
@@ -138,7 +137,7 @@ Content-Type: application/json
```http
HTTP/1.1 200
Content-Type: application/json
```
### Delete user in current organization
@@ -172,7 +171,7 @@ Content-Type: application/json
### Update current Organization
`PUT /api/org`
`PUT /api/org`
**Required permissions**
@@ -202,7 +201,7 @@ Content-Type: application/json
### Add a new user to the current organization
`POST /api/org/users`
`POST /api/org/users`
Adds a global user to the current organization.
@@ -238,7 +237,7 @@ Content-Type: application/json
only linked to an organization and an organization role. They cannot be given the permission of server
admin, only users can be given that permission. So in order to use these API calls you will have to
use Basic Auth and the Grafana user must have the Grafana Admin permission (The default admin user
is called `admin` and has permission to use this API).
is called `admin` and has permission to use this API).
### Get Organization by Id
@@ -283,7 +282,7 @@ is called `admin` and has permission to use this API).
| Action | Scope | Note |
| --------- | ----- | ------------------------------ |
| orgs:read | N/A | Needs to be assigned globally. |
**Example Request**:
```http
@@ -325,7 +324,7 @@ Content-Type: application/json
Note: The api will work in the following two ways
1. Need to set GF_USERS_ALLOW_ORG_CREATE=true
1. Need to set GF_USERS_ALLOW_ORG_CREATE=true
2. Set the config value users.allow_org_create to true in ini file
**Example Response**:
@@ -367,7 +366,7 @@ Content-Type: application/json
```http
HTTP/1.1 200
Content-Type: application/json
Content-Type: application/json
```
@@ -410,7 +409,7 @@ Content-Type: application/json
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
**Required permissions**
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
| Action | Scope |
@@ -452,7 +451,7 @@ Content-Type: application/json
GET /api/orgs/1/users HTTP/1.1
Accept: application/json
Content-Type: application/json
```
```
Note: The api will only work when you pass the admin name and password
to the request HTTP URL, like http://admin:admin@localhost:3000/api/orgs/1/users
@@ -487,7 +486,7 @@ Content-Type: application/json
Content-Type: application/json
```
**Example Response**:
```http
@@ -517,7 +516,7 @@ Content-Type: application/json
Accept: application/json
Content-Type: application/json
```
```
**Example Response**:
@@ -558,7 +557,7 @@ Content-Type: application/json
```
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
@@ -594,7 +593,7 @@ Content-Type: application/json
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
@@ -629,7 +628,7 @@ Content-Type: application/json
Only works with Basic Authentication (username and password), see [introduction](#admin-organizations-api).
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.

3
docs/sources/developers/http_api/reporting.md
View File

@@ -11,8 +11,7 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
> Reporting is only available in Grafana Enterprise. Read more about [Grafana Enterprise]({{< relref "../../enterprise" >}}).
> If you have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
> Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Send a report

31
docs/sources/developers/http_api/serviceaccount.md
View File

@@ -7,16 +7,15 @@ title = "Service account HTTP API "
# Service account API
> If you are running Grafana Enterprise and have [Fine-grained access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
> Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/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
**Required permissions**
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
| Action | Scope |
| -------------------- | ------------------------- |
@@ -81,9 +80,9 @@ Content-Type: application/json
See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
| Action | Scope |
| Action | Scope |
| -------------------- | ------------------ |
| serviceaccounts:read | serviceaccounts:\* |
| serviceaccounts:read | serviceaccounts:\* |
**Example Request**:
@@ -129,9 +128,9 @@ Content-Type: application/json
Requires basic authentication and that the authenticated user is a Grafana Admin.
**Example Response**:
```http
HTTP/1.1 200
HTTP/1.1 200
Content-Type: application/json
```
@@ -172,9 +171,9 @@ 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.
@@ -224,9 +223,9 @@ Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
Requires basic authentication and that the authenticated user is a Grafana Admin.
Requires basic authentication and that the authenticated user is a Grafana Admin.
**Example Response**:
**Example Response**:
```http
HTTP/1.1 200
@@ -266,9 +265,9 @@ Content-Type: application/json
`POST /api/serviceaccounts/:id/tokens`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#serviceaccount-api" >}}) for an explanation.
See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
| Action | Scope |
| --------------------- | ------------------ |
@@ -307,9 +306,9 @@ Content-Type: application/json
`DELETE /api/serviceaccounts/:id/tokens/:tokenId`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#serviceaccount-api" >}}) for an explanation.
See note in the [introduction]({{< ref "#service-account-api" >}}) for an explanation.
| Action | Scope |
| --------------------- | ------------------ |

23
docs/sources/developers/http_api/team.md
View File

@@ -16,8 +16,7 @@ Access to these API endpoints is restricted as follows:
- If you enable `editors_can_admin` configuration flag, then Organization Editors can create teams and manage teams where they are Admin.
- If you enable `editors_can_admin` configuration flag, Editors can find out whether a team that they are not members of exists by trying to create a team with the same name.
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, access to endpoints will be controlled by role-based access control permissions.
> Refer to specific endpoints to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Team Search With Paging
@@ -27,7 +26,7 @@ or
`GET /api/teams/search?name=myteam`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
@@ -90,7 +89,7 @@ The `name` parameter returns a single team if the parameter matches the `name` f
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
```
**Example Response**:
@@ -136,7 +135,7 @@ The Team `name` needs to be unique. `name` is required and `email`,`orgId` is op
```http
HTTP/1.1 200
Content-Type: application/json
```
Status Codes:
@@ -181,7 +180,7 @@ There are two fields that can be updated for a team: `name` and `email`.
Status Codes:
- **200** - Ok
- **401** - Unauthorized
- **401** - Unauthorized
- **403** - Permission denied
- **404** - Team not found
- **409** - Team name is taken
@@ -224,7 +223,7 @@ Status Codes:
## Get Team Members
`GET /api/teams/:teamId/members`
`GET /api/teams/:teamId/members`
**Required permissions**
@@ -261,7 +260,7 @@ Status Codes:
`POST /api/teams/:teamId/members`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.
@@ -314,7 +313,7 @@ Status Codes:
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
```
**Example Response**:
@@ -356,7 +355,7 @@ Status Codes:
```http
HTTP/1.1 200
Content-Type: application/json
Content-Type: application/json
```
@@ -393,7 +392,7 @@ Status Codes:
**Example Response**:
```http
HTTP/1.1 200
HTTP/1.1 200
Content-Type: text/plain; charset=utf-8
```
@@ -427,7 +426,7 @@ Content-Type: application/json
`PUT /api/teams/:teamId/preferences`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#team-api" >}}) for an explanation.

17
docs/sources/developers/http_api/user.md
View File

@@ -7,14 +7,13 @@ title = "User HTTP API "
# User API
> If you are running Grafana Enterprise and have [Role-based access control]({{< relref "../../enterprise/access-control/_index.md" >}}) enabled, for some endpoints you would need to have relevant permissions.
> Refer to specific resources to understand what permissions are required.
> If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "../../enterprise/access-control/custom-role-actions-scopes" >}}) for more information.
## Search Users
`GET /api/users?perpage=10&page=1`
#### Required permissions
**Required permissions**
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
@@ -69,7 +68,7 @@ Content-Type: application/json
**Example Response**:
```http
HTTP/1.1 200
HTTP/1.1 200
Content-Type: application/json
{
```
@@ -130,7 +129,7 @@ Content-Type: application/json
```http
GET /api/users/lookup?loginOrEmail=admin HTTP/1.1
Accept: application/json
Accept: application/json
Content-Type: application/json
Authorization: Basic YWRtaW46YWRtaW4=
```
@@ -176,7 +175,7 @@ Content-Type: application/json
Content-Type: application/json
```
## Get Organizations for user
`GET /api/users/:id/orgs`
@@ -231,7 +230,7 @@ Content-Type: application/json
Requires basic authentication and that the authenticated user is a Grafana Admin.
**Example Response**:
**Example Response**:
```http
HTTP/1.1 200
@@ -270,7 +269,7 @@ Content-Type: application/json
Changes the password for the user. Requires basic authentication.
**Example Request**:
**Example Request**:
```http
PUT /api/user/password HTTP/1.1
@@ -308,7 +307,7 @@ Content-Type: application/json
**Example Request**:
```http
```http
POST /api/users/7/using/2 HTTP/1.1
Authorization: Basic YWRtaW46YWRtaW4=
```