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

PackageJson: Prettify markdown/mdx on commit with lint-staged (#37616)

Browse Source 
* Format md,mdx files with prettier on lint-staged

* Manually run prettier on docs/sources
This commit is contained in:
Connor Lindsey
2021-08-06 07:52:36 -06:00
committed by GitHub
parent e9c032f10f
commit b78a67cec7
301 changed files with 3216 additions and 2980 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/sources/http_api/access_control.md
+123 -123
View File
@@ -9,7 +9,7 @@ aliases = ["/docs/grafana/latest/http_api/accesscontrol/"]
> 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.
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" >}}).
@@ -22,9 +22,9 @@ Returns an indicator to check if fine-grained access control is enabled or not.
### Required permissions
Action | Scope
--- | --- |
status:accesscontrol | services:accesscontrol
| Action | Scope |
| -------------------- | ---------------------- |
| status:accesscontrol | services:accesscontrol |
#### Example request
@@ -47,12 +47,12 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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
@@ -60,14 +60,14 @@ Code | Description
`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.
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:*
| Action | Scope |
| ---------- | -------- |
| roles:list | roles:\* |
#### Example request
@@ -107,11 +107,11 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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
@@ -121,9 +121,9 @@ Get a role for the given UID.
#### Required permissions
Action | Scope
--- | --- |
roles:read | roles:*
| Action | Scope |
| ---------- | -------- |
| roles:read | roles:\* |
#### Example request
@@ -166,11 +166,11 @@ Content-Type: application/json; charset=UTF-8
#### Status codes
Code | Description
--- | --- |
200 | Role is returned.
403 | Access denied
500 | Unexpected error. Refer to body and/or server logs for more details.
| 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
@@ -183,9 +183,9 @@ Creates a new custom role and maps given permissions to that role. Note that rol
`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
| Action | Scope |
| ----------- | -------------------- |
| roles:write | permissions:delegate |
#### Example request
@@ -211,21 +211,21 @@ Content-Type: application/json
#### 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.
| 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.
| 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
@@ -254,12 +254,12 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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
@@ -272,9 +272,9 @@ Update the role with the given UID, and it's permissions with the given UID. The
`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
| Action | Scope |
| ----------- | -------------------- |
| roles:write | permissions:delegate |
#### Example request
@@ -284,9 +284,9 @@ Accept: application/json
Content-Type: application/json
{
"version": 2,
"version": 2,
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"action": "roles:delete",
@@ -302,19 +302,19 @@ Content-Type: application/json
#### 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.
| 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.
| 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
@@ -323,9 +323,9 @@ HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"version": 3,
"version": 3,
"name": "custom:delete:create:roles",
"description": "My custom role which gives users permissions to delete and create roles",
"description": "My custom role which gives users permissions to delete and create roles",
"permissions": [
{
"action": "roles:delete",
@@ -347,13 +347,13 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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
@@ -366,9 +366,9 @@ Delete a role with the given UID, and it's permissions. If the role is assigned
`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
| Action | Scope |
| ------------ | -------------------- |
| roles:delete | permissions:delegate |
#### Example request
@@ -379,9 +379,9 @@ 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.
| Param | Type | Required | Description |
| ----- | ------- | -------- | ----------------------------------------------------------------------- |
| force | boolean | No | When set to `true`, the role will be deleted with all it's assignments. |
#### Example response
@@ -396,16 +396,16 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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.
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
@@ -415,9 +415,9 @@ Gets all built-in role assignments.
#### Required permissions
Action | Scope
--- | --- |
roles.builtin:list | roles:*
| Action | Scope |
| ------------------ | -------- |
| roles.builtin:list | roles:\* |
#### Example request
@@ -470,11 +470,11 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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
@@ -484,12 +484,12 @@ 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.
`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
| Action | Scope |
| ----------------- | -------------------- |
| roles.builtin:add | permissions:delegate |
#### Example request
@@ -507,11 +507,11 @@ Content-Type: application/json
#### 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.
| 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
@@ -526,13 +526,13 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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
@@ -545,9 +545,9 @@ Deletes a built-in role assignment (for one of _Viewer_, _Editor_, _Admin_, or _
`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
| Action | Scope |
| -------------------- | -------------------- |
| roles.builtin:remove | permissions:delegate |
#### Example request
@@ -558,9 +558,9 @@ 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.
| 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
@@ -575,10 +575,10 @@ Content-Type: application/json; charset=UTF-8
#### 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.
| 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. |