public/grafana
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs: Document fine-grained access control (#33563)

Browse Source
This commit is contained in:
Vardan Torosyan
2021-05-20 09:53:34 -07:00
committed by GitHub
parent 292789ba2d
commit 676ddac088
31 changed files with 1436 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/http_api/_index.md
+1
View File
@@ -37,6 +37,7 @@ dashboards, creating users and updating data sources.
Grafana Enterprise includes all of the Grafana OSS APIs as well as those that follow:
- [Fine-Grained Access Control API]({{< relref "access_control.md" >}})
- [Data Source Permissions API]({{< relref "datasource_permissions.md" >}})
- [External Group Sync API]({{< relref "external_group_sync.md" >}})
- [License API]({{< relref "licensing.md" >}})
docs/sources/http_api/access_control.md
+584
View File
@@ -0,0 +1,584 @@
+++
title = "Fine-grained access control HTTP API "
description = "Fine-grained access control API"
keywords = ["grafana", "http", "documentation", "api", "fine-grained-access-control", "acl", "enterprise"]
aliases = ["/docs/grafana/latest/http_api/accesscontrol/"]
+++
# Fine-grained access control API
> Fine-grained 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 built-in role assignments.
To use the API, you would need to [enable fine-grained access control]({{< relref "../enterprise/access-control/_index.md#enable-fine-grained-access-control" >}}).
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" >}}).
## Get status
`GET /api/access-control/status`
Returns an indicator to check if fine-grained access control is enabled or not.
### Required permissions
Action | Scope
--- | --- |
status:accesscontrol | services:accesscontrol
#### Example request
```http
GET /api/access-control/check
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"enabled": true
}
```
#### Status codes
Code | Description
--- | --- |
200 | Returned a flag indicating if the fine-grained access control is enabled or no.
403 | Access denied
404 | Not found, an indication that fine-grained access control is not available at all.
500 | Unexpected error. Refer to body and/or server logs for more details.
## Create and manage custom roles
### Get all roles
`GET /api/access-control/roles`
Gets all existing roles. The response contains all global and organization local roles, for the organization which user is signed in.
Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
#### Required permissions
Action | Scope
--- | --- |
roles:list | roles:*
#### Example request
```http
GET /api/access-control/roles
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
[
{
"version": 1,
"uid": "Kz9m_YjGz",
"name": "grafana:roles:reporting:admin:edit",
"description": "Gives access to edit any report or the organization's general reporting settings.",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
{
"version": 5,
"uid": "vi9mlLjGz",
"name": "grafana:roles:permissions:admin:read",
"description": "Gives access to read and list roles and permissions, as well as built-in role assignments.",
"global": true,
"updated": "2021-05-13T22:41:49+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
]
```
#### Status codes
Code | Description
--- | --- |
200 | Global and organization local roles are returned.
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
### Get a role
`GET /api/access-control/roles/:uid`
Get a role for the given UID.
#### Required permissions
Action | Scope
--- | --- |
roles:read | roles:*
#### Example request
```http
GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 2,
"uid": "jZrmlLCGk",
"name": "grafana:roles:permissions:admin:edit",
"description": "Gives access to create, update and delete roles, as well as manage built-in role assignments.",
"global": true,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate",
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
{
"action": "roles:list",
"scope": "roles:*",
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
],
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is returned.
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
### Create a new custom role
`POST /api/access-control/roles`
Creates a new custom role and maps given permissions to that role. Note that roles with the same prefix as [Predefined Roles]({{< relref "../enterprise/access-control/roles.md" >}}) can't be created.
#### Required permissions
`permission:delegate` scope ensures that users can only create custom roles with the same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to create a custom role which allows to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
roles:write | permissions:delegate
#### Example request
```http
POST /api/access-control/roles
Accept: application/json
Content-Type: application/json
{
"version": 1,
"uid": "jZrmlLCGka",
"name": "custom:delete:roles",
"description": "My custom role which gives users permissions to delete roles",
"global": true,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate"
}
]
}
```
#### JSON body schema
Field Name | Date Type | Required | Description
--- | --- | --- | ---
uid | string | No | UID of the role. If not present, the UID will be automatically created for you and returned in response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
global | boolean | No | A flag indicating if the role is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request. Refer to the [Role scopes]({{< relref "../enterprise/access-control/roles.md#role-scopes" >}}) for more information.
version | number | No | Version of the role. If not present, version 0 will be assigned to the role and returned in the response. Refer to the [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
name | string | Yes | Name of the role. Refer to [Custom roles]({{< relref "../enterprise/access-control/roles.md#custom-roles" >}}) for more information.
description | string | No | Description of the role.
permissions | Permission | No | If not present, the role will be created without any permissions.
**Permission**
Field Name | Data Type | Required | Description
--- | --- | --- | ---
action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions.
scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 2,
"uid": "jZrmlLCGka",
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"global": true,
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate",
"updated": "2021-05-13T23:19:46+02:00",
"created": "2021-05-13T23:19:46+02:00"
}
],
"updated": "2021-05-13T23:20:51.416518+02:00",
"created": "2021-05-13T23:19:46+02:00"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is updated.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
### Update a custom role
`PUT /api/access-control/roles/:uid`
Update the role with the given UID, and it's permissions with the given UID. The operation is idempotent and all permissions of the role will be replaced with what is in the request. You would need to increment the version of the role with each update, otherwise the request will fail.
#### Required permissions
`permission:delegate` scope ensures that users can only update custom roles with the same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to update a custom role which allows to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
roles:write | permissions:delegate
#### Example request
```http
PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json
{
"version": 2,
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate"
},
{
"action": "roles:create",
"scope": "permissions:delegate"
}
]
}
```
#### JSON body schema
Field Name | Data Type | Required | Description
--- | --- | --- | ---
version | number | Yes | Version of the role. Must be incremented for update to work.
name | string | Yes | Name of the role.
description | string | No | Description of the role.
permissions | List of Permissions | No | The full list of permissions the role should have after the update.
**Permission**
Field Name | Data Type | Required | Description
--- | --- | --- | ---
action | string | Yes | Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md" >}}) for full list of available actions.
scope | string | No | If not present, no scope will be mapped to the permission. Refer to [Permissions]({{< relref "../enterprise/access-control/permissions.md#scope-definitions" >}}) for full list of available scopes.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 3,
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"action": "roles:delete",
"scope": "permissions:delegate",
"updated": "2021-05-13T23:19:46.546146+02:00",
"created": "2021-05-13T23:19:46.546146+02:00"
},
{
"action": "roles:create",
"scope": "permissions:delegate",
"updated": "2021-05-13T23:19:46.546146+02:00",
"created": "2021-05-13T23:19:46.546146+02:00"
}
],
"updated": "2021-05-13T23:19:46.540987+02:00",
"created": "2021-05-13T23:19:46.540986+02:00"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is updated.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
404 | Role was not found to update.
500 | Unexpected error. Refer to body and/or server logs for more details.
### Delete a custom role
`DELETE /api/access-control/roles/:uid?force=false`
Delete a role with the given UID, and it's permissions. If the role is assigned to a built-in role, the deletion operation will fail, unless `force` query param is set to `true`, and in that case all assignments will also be deleted.
#### Required permissions
`permission:delegate` scope ensures that users can only delete a custom role with the same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to delete a custom role which allows to do that.
Action | Scope
--- | --- |
roles:delete | permissions:delegate
#### Example request
```http
DELETE /api/access-control/roles/jZrmlLCGka?force=true
Accept: application/json
```
#### Query parameters
Param | Type | Required | Description
--- | --- | --- | ---
force | boolean | No | When set to `true`, the role will be deleted with all it's assignments.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Role deleted"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role is deleted.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
## Create and remove built-in role assignments
API set allows to create or remove [built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) and list current assignments.
### Get all built-in role assignments
`GET /api/access-control/builtin-roles`
Gets all built-in role assignments.
#### Required permissions
Action | Scope
--- | --- |
roles.builtin:list | roles:*
#### Example request
```http
GET /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json
```
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"Admin": [
{
"version": 1,
"uid": "qQui_LCMk",
"name": "grafana:roles:users:org:edit",
"description": "",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
},
{
"version": 1,
"uid": "PeXmlYjMk",
"name": "grafana:roles:users:org:read",
"description": "",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
],
"Grafana Admin": [
{
"version": 1,
"uid": "qQui_LCMk",
"name": "grafana:roles:users:org:edit",
"description": "",
"global": true,
"updated": "2021-05-13T16:24:26+02:00",
"created": "2021-05-13T16:24:26+02:00"
}
]
}
```
#### Status codes
Code | Description
--- | --- |
200 | Built-in role assignments are returned.
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
### Create a built-in role assignment
`POST /api/access-control/builtin-roles`
Creates a new built-in role assignment.
#### Required permissions
`permission:delegate` scope ensures that users can only create built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to create a built-in role assignment which will allow to do that. This is done to prevent escalation of privileges.
Action | Scope
--- | --- |
roles.builtin:add | permissions:delegate
#### Example request
```http
POST /api/access-control/builtin-roles
Accept: application/json
Content-Type: application/json
{
"roleUid": "LPMGN99Mk",
"builtinRole": "Grafana Admin",
"global": false
}
```
#### JSON body schema
Field Name | Date Type | Required | Description
--- | --- | --- | ---
roleUid | string | Yes | UID of the role.
builtinRole | boolean | Yes | Can be one of `Viewer`, `Editor`, `Admin` or `Grafana Admin`.
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to create organization local assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Built-in role grant added"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role was assigned to built-in role.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
404 | Role not found
500 | Unexpected error. Refer to body and/or server logs for more details.
### Remove a built-in role assignment
`DELETE /api/access-control/builtin-roles/:builtinRole/roles/:roleUID`
Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _Grafana Admin_) to the role with the provided UID.
#### Required permissions
`permission:delegate` scope ensures that users can only remove built-in role assignments with the roles which have same, or a subset of permissions which the user has.
For example, if a user does not have required permissions for creating users, they won't be able to remove a built-in role assignment which allows to do that.
Action | Scope
--- | --- |
roles.builtin:remove | permissions:delegate
#### Example request
```http
DELETE /api/access-control/builtin-roles/Grafana%20Admin/roles/LPMGN99Mk?global=false
Accept: application/json
```
#### Query parameters
Param | Type | Required | Description
--- | --- | --- | ---
global | boolean | No | A flag indicating if the assignment is global or not. If set to `false`, the default org ID of the authenticated user will be used from the request to remove assignment. Refer to the [Built-in role assignments]({{< relref "../enterprise/access-control/roles.md#built-in-role-assignments" >}}) for more information.
#### Example response
```http
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"message": "Built-in role grant removed"
}
```
#### Status codes
Code | Description
--- | --- |
200 | Role was unassigned from built-in role.
400 | Bad request (invalid json, missing content-type, missing or invalid fields, etc.).
403 | Access denied
404 | Role not found.
500 | Unexpected error. Refer to body and/or server logs for more details.
docs/sources/http_api/admin.md
+69
View File
@@ -11,6 +11,9 @@ 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 [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.
## Settings
`GET /api/admin/settings`
@@ -209,6 +212,14 @@ Content-Type: application/json
Create new user. Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:create | n/a
**Example Request**:
```http
@@ -243,6 +254,14 @@ Content-Type: application/json
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.
Action | Scope
--- | --- |
users.password:update | global:users:*
**Example Request**:
```http
@@ -268,6 +287,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.permissions:update | global:users:*
**Example Request**:
```http
@@ -293,6 +320,14 @@ Content-Type: application/json
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:delete | global:users:*
**Example Request**:
```http
@@ -353,6 +388,14 @@ 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
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.authtoken:list | global:users:*
**Example Request**:
```http
@@ -404,6 +447,14 @@ 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
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.authtoken:update | global:users:*
**Example Request**:
```http
@@ -436,6 +487,14 @@ 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
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.logout | global:users:*
**Example Request**:
```http
@@ -465,12 +524,22 @@ Content-Type: application/json
`POST /api/admin/provisioning/notifications/reload`
`POST /api/admin/provisioning/accesscontrol/reload`
Reloads the provisioning config files for specified type and provision entities again. It won't return
until the new provisioned entities are already stored in the database. In case of dashboards, it will stop
polling for changes in dashboard files and then restart it with new configurations after returning.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
#### Required permissions
See note in the [introduction]({{< ref "#admin-api" >}}) for an explanation.
Action | Scope | Provision entity
--- | --- | ---
provisioning:reload | service:accesscontrol | accesscontrol
**Example Request**:
```http
docs/sources/http_api/org.md
+67 -1
View File
@@ -5,13 +5,15 @@ keywords = ["grafana", "http", "documentation", "api", "organization"]
aliases = ["/docs/grafana/latest/http_api/organization/"]
+++
# Organization API
The Organization HTTP API is divided in two resources, `/api/org` (current organization)
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 [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.
## Current Organization API
### Get current Organization
@@ -46,6 +48,14 @@ Content-Type: application/json
Returns all org users within the current organization.
Accessible to users with org admin role.
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:read | users:*
**Example Request**:
```http
@@ -112,6 +122,14 @@ Content-Type: application/json
`PATCH /api/org/users/:userId`
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users.role:update | users:*
**Example Request**:
```http
@@ -138,6 +156,14 @@ Content-Type: application/json
`DELETE /api/org/users/:userId`
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:remove | users:*
**Example Request**:
```http
@@ -188,6 +214,14 @@ Content-Type: application/json
Adds a global user to the current organization.
#### Required permissions
See note in the [introduction]({{< ref "#organization-api" >}}) for an explanation.
Action | Scope
--- | --- |
org.users:add | users:*
**Example Request**:
```http
@@ -407,6 +441,14 @@ 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
--- | --- |
org.users:read | users:*
**Example Request**:
```http
@@ -440,6 +482,14 @@ 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
--- | --- |
org.users:add | users:*
**Example Request**:
```http
@@ -468,6 +518,14 @@ 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
--- | --- |
org.users.role:update | users:*
**Example Request**:
```http
@@ -495,6 +553,14 @@ 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
--- | --- |
org.users:remove | users:*
**Example Request**:
```http
docs/sources/http_api/reporting.md
+12 -2
View File
@@ -11,7 +11,9 @@ 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 [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.
## Send a report
> Only available in Grafana Enterprise v7.0+.
@@ -22,6 +24,14 @@ This API allows you to interact programmatically with the [Reporting]({{< relref
Generate and send a report. This API waits for the report to be generated before returning. We recommend that you set the client's timeout to at least 60 seconds.
#### Required permissions
See note in the [introduction]({{< ref "#reporting-api" >}}) for an explanation.
Action | Scope
--- | --- |
reports:send | n/a
### Example request
```http
@@ -63,4 +73,4 @@ Code | Description
401 | Authentication failed, refer to [Authentication API]({{< relref "../http_api/auth.md" >}}).
403 | User is authenticated but is not authorized to generate the report.
404 | Report not found.
500 | Unexpected error or server misconfiguration. Refer to body and/or server logs for more details.
500 | Unexpected error or server misconfiguration. Refer to server logs for more details.
docs/sources/http_api/user.md
+60 -1
View File
@@ -5,12 +5,23 @@ keywords = ["grafana", "http", "documentation", "api", "user"]
aliases = ["/docs/grafana/latest/http_api/user/"]
+++
# User HTTP resources / actions
# User 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.
## Search Users
`GET /api/users?perpage=10&page=1`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | global:users:*
**Example Request**:
```http
@@ -58,6 +69,14 @@ Content-Type: application/json
`GET /api/users/search?perpage=10&page=1&query=mygraf`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | global:users:*
**Example Request**:
```http
@@ -111,6 +130,14 @@ Content-Type: application/json
`GET /api/users/:id`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | users:*
**Example Request**:
```http
@@ -148,6 +175,14 @@ Content-Type: application/json
`GET /api/users/lookup?loginOrEmail=user@mygraf.com`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | global:users:*
**Example Request using the email as option**:
```http
@@ -195,6 +230,14 @@ Content-Type: application/json
`PUT /api/users/:id`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:write | users:*
**Example Request**:
```http
@@ -226,6 +269,14 @@ Content-Type: application/json
`GET /api/users/:id/orgs`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users:read | users:*
**Example Request**:
```http
@@ -256,6 +307,14 @@ Content-Type: application/json
`GET /api/users/:id/teams`
#### Required permissions
See note in the [introduction]({{< ref "#user-api" >}}) for an explanation.
Action | Scope
--- | --- |
users.teams:read | users:*
**Example Request**:
```http