Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Ресурсы для разработчиковbreadcrumb arrow API Grafanabreadcrumb arrow Справочное руководство по HTTP API Grafanabreadcrumb arrow Устаревший HTTP API Grafanabreadcrumb arrow HTTP API RBAC

API RBAC

Note

Starting in Grafana 13, /api endpoints are being deprecated in favor of the /apis route. Note that while Grafana is working on migrating existing APIs, currently there may not be an exact match to the legacy API you’re using.

This change doesn’t disrupt or break your current setup. Legacy APIs are not being disabled and remain fully accessible and operative, but /api routes will no longer be updated.

To learn more refer to the new API structure in Grafana.

Используйте этот API для создания, обновления, удаления, получения и перечисления ролей.

Чтобы проверить, какие базовые или фиксированные роли имеют требуемые права, см. Определения ролей RBAC.

Требования

API управления доступом на основе ролей доступен только в Grafana Cloud или Grafana Enterprise. Подробнее о Grafana Enterprise.

Получение состояния

GET /api/access-control/status

Возвращает индикатор для проверки того, включено ли управление доступом на основе ролей.

Требуемые права

Действие Область
status:accesscontrol services:accesscontrol

Пример запроса

http 
GET /api/access-control/status
Accept: application/json
Content-Type: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "enabled": true
}

Коды состояния

Код Описание
200 Возвращён флаг, указывающий, включено ли управление доступом на основе ролей.
403 Доступ запрещён
404 Не найдено — признак того, что управление доступом на основе ролей вообще недоступно.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Создание настраиваемых ролей и управление ими

Получение всех ролей

GET /api/access-control/roles

Возвращает все существующие роли. Ответ содержит все глобальные и локальные для организации роли для организации, в которой авторизован пользователь.

Параметры запроса:

  • includeHidden: необязательно. Установите true, чтобы включить роли, которые являются hidden.

Требуемые права

Действие Область
roles:read roles:*

Пример запроса

http 
GET /api/access-control/roles
Accept: application/json
Content-Type: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 3,
        "uid": "XvHQJq57z",
        "name": "fixed:reports:reader",
        "displayName": "Report reader",
        "description": "Read all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    },
    {
        "version": 5,
        "uid": "vi9mlLjGz",
        "name": "fixed:datasources.permissions:writer",
        "description: "Create, read or delete data source permissions.",
        "global": true,
        "updated": "2021-05-13T22:41:49+02:00",
        "created": "2021-05-13T16:24:26+02:00"
    }
]

Коды состояния

Код Описание
200 Глобальные и локальные для организации роли возвращены.
403 Доступ запрещён
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Получение роли

GET /api/access-control/roles/:uid

Возвращает роль для заданного UID.

Требуемые права

Действие Область
roles:read roles:*

Пример запроса

http 
GET /api/access-control/roles/PYnDO3rMk
Accept: application/json
Content-Type: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version": 4,
    "uid": "6dNwJq57z",
    "name": "fixed:reports:writer",
    "displayName": "Report writer",
    "description": "Create, read, update, or delete all reports and shared report settings.",
    "group": "Reports",
    "permissions": [
        {
            "action": "reports:delete",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:read",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:send",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:create",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports:write",
            "scope": "reports:*",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:read",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        },
        {
            "action": "reports.settings:write",
            "scope": "",
            "updated": "2021-11-19T10:48:00+01:00",
            "created": "2021-11-19T10:48:00+01:00"
        }
    ],
    "updated": "2021-11-19T10:48:00+01:00",
    "created": "2021-11-19T10:48:00+01:00",
    "global": false
}

Коды состояния

Код Описание
200 Роль возвращена.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Создание новой настраиваемой роли

POST /api/access-control/roles

Создаёт новую настраиваемую роль и сопоставляет заданные права этой роли. Обратите внимание, что роли с таким же префиксом, как у фиксированных ролей, создать нельзя.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут создавать настраиваемые роли только с теми же правами или подмножеством прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет создать настраиваемую роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
roles:write permissions:type:delegate

Пример запроса

http 
POST /api/access-control/roles
Accept: application/json
Content-Type: application/json

{
    "uid": "jZrmlLCGka",
    "name": "custom:delete:roles",
    "displayName": "custom delete roles",
    "description": "My custom role which gives users permissions to delete roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:type:delegate"
        }
    ]
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
uid string Нет UID роли. Если не указан, UID автоматически создаётся за вас и возвращается в ответе. Дополнительные сведения см. в разделе Настраиваемые роли.
global boolean Нет Флаг, указывающий, является ли роль глобальной. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя.
version number Нет Устарело. Игнорируется при создании; сервер всегда присваивает новым ролям версию 1. Ответ возвращает присвоенную версию.
name string Да Имя роли. Дополнительные сведения см. в разделе Настраиваемые роли.
description string Нет Описание роли.
displayName string Нет Отображаемое имя роли, видимое в интерфейсе.
group string Нет Имя группы, к которой принадлежит роль.
hidden boolean Нет Указывает, скрыта ли роль. Если установлено true, роль не отображается в выборе ролей. Она не будет перечисляться конечными точками API, если не указано явно.
permissions Permission Нет Если не указано, роль будет создана без каких-либо прав.

Permission

Имя поля Тип данных Обязательно Описание
action string Да Полный список доступных действий см. в разделе Действия и области действия настраиваемых ролей.
scope string Нет Если не указано, к праву не будет сопоставлено никакой области. Полный список доступных областей см. в разделе Действия и области действия настраиваемых ролей.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version": 2,
    "uid": "jZrmlLCGka",
    "name": "custom:delete:create:roles",
    "displayName": "custom delete create roles",
    "description": "My custom role which gives users permissions to delete and create roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:type: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"
}

Ошибки валидации при создании роли

Проверка прав выполняется только когда включена валидация прав (rbac.permission_validation_enabled = true).

Она включена по умолчанию начиная с Grafana 10.2.

Недопустимое действие

Следующий пример показывает запрос с недопустимым действием. Действие serviceaccounts.permissions:reader не является допустимым действием. Допустимым действием должно быть serviceaccounts.permissions:read.

http 
POST /api/access-control/roles HTTP/1.1
Content-Type: application/json
{
	"Name": "Read Service Account with id 6",
	"Permissions": [
			{
			"action": "serviceaccounts.permissions:reader",
			"scope": "serviceaccounts:uid:6"
		}
	]
}
http 
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
	"extra": {
		"validationError": "the provided action was not found in the list of valid actions: serviceaccounts.permissions:reader"
	},
	"message": "Permission contains an invalid action",
	"messageId": "accesscontrol.permission-invalid-action",
	"statusCode": 400,
	"traceID": ""
}
Недопустимая область действия

Следующий пример показывает запрос с недопустимой областью действия. Область serviceaccounts:serviceaccount6 не является допустимой областью для действия serviceaccounts.permissions:read. Допустимые области для этого действия: *, serviceaccounts:* и serviceaccounts:id:*.

http 
POST /api/access-control/roles HTTP/1.1
Content-Type: application/json
{
	"Name": "Read Service Account with id 6",
	"Permissions": [
			{
			"action": "serviceaccounts.permissions:read",
			"scope": "serviceaccounts:serviceaccount6"
		}
	]
}
http 
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
	"extra": {
		"validationError": "unknown scope: serviceaccounts:serviceaccount6 for action: serviceaccounts.permissions:read provided, expected prefixes are [* serviceaccounts:* serviceaccounts:id:*]"
	},
	"message": "Invalid scope",
	"messageId": "accesscontrol.permission-invalid-scope",
	"statusCode": 400,
	"traceID": ""
}

Коды состояния

Код Описание
200 Роль обновлена.
400 Некорректный запрос (неверный json, отсутствующий content-type, отсутствующие или недопустимые поля и т. д.).
403 Доступ запрещён (одно из указанных прав не назначено запрашивающему)
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Обновление роли

PUT /api/access-control/roles/:uid

Обновляет роль с заданным UID и её права. Операция идемпотентна, и все права роли будут заменены на основе содержимого запроса. Передайте текущую version роли (из последнего ответа GET или list) для оптимистичной блокировки; запрос завершится ошибкой, если роль была обновлена где-то ещё. Сервер автоматически увеличивает хранимую версию при каждом обновлении.

Вы можете обновлять права ролей custom и basic. Однако роли fixed обновлять нельзя.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут обновлять настраиваемые роли только с теми же правами или подмножеством прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет обновить настраиваемую роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
roles:write permissions:type:delegate

Пример запроса

http 
PUT /api/access-control/roles/jZrmlLCGka
Accept: application/json
Content-Type: application/json

{
    "version": 3,
    "name": "custom:delete:write:roles",
    "displayName": "custom delete write roles",
    "description": "My custom role which gives users permissions to delete and write roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "global": false,
    "permissions": [
        {
            "action": "roles:delete",
            "scope": "permissions:type:delegate"
        },
        {
            "action": "roles:write",
            "scope": "permissions:type:delegate"
        }
    ]
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
version number Да Текущая версия роли (из последнего GET или list). Обязательна для оптимистичной блокировки; запрос завершится ошибкой, если хранимая версия больше. Устарело как входное значение для установки значения — сервер автоматически увеличивает хранимую версию при обновлении.
name string Да Имя роли.
description string Нет Описание роли.
displayName string Нет Отображаемое имя роли, видимое в интерфейсе.
group string Нет Имя группы, к которой принадлежит роль.
hidden boolean Нет Указывает, скрыта ли роль. Если установлено true, роль не отображается в выборе ролей. Она не будет перечисляться конечными точками API, если не указано явно.
permissions List of Permissions Нет Полный список прав для роли после обновления.

Permission

Имя поля Тип данных Обязательно Описание
action string Да Полный список доступных действий см. в разделе Действия и области действия настраиваемых ролей.
scope string Нет Если не указано, к праву не будет сопоставлено никакой области. Полный список доступных областей см. в разделе Действия и области действия настраиваемых ролей.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "version":3,
    "uid":"jZrmlLCGka",
    "name":"custom:delete:write:roles",
    "displayName":"custom delete write roles",
    "description":"My custom role which gives users permissions to delete and write roles",
    "group":"My Group",
    "displayName": "My Custom Role",
    "permissions":[
        {
            "action":"roles:delete",
            "scope":"permissions:type:delegate",
            "updated":"2021-08-06T18:27:40+02:00",
            "created":"2021-08-06T18:27:40+02:00"
        },
        {
            "action":"roles:write",
            "scope":"permissions:type:delegate",
            "updated":"2021-08-06T18:27:41+02:00",
            "created":"2021-08-06T18:27:41+02:00"
        }
    ],
    "updated":"2021-08-06T18:27:41+02:00",
    "created":"2021-08-06T18:27:40+02:00",
    "global":false
}

Ошибки валидации при обновлении роли

Проверка прав выполняется только когда включена валидация прав (rbac.permission_validation_enabled = true).

Она включена по умолчанию начиная с Grafana 10.2.

Дополнительные сведения см. в разделе Ошибки валидации при создании роли.

Коды состояния

Код Описание
200 Роль обновлена.
400 Некорректный запрос (неверный json, отсутствующий content-type, отсутствующие или недопустимые поля и т. д.).
403 Доступ запрещён (одно из указанных прав не назначено запрашивающему)
404 Роль для обновления не найдена.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Удаление настраиваемой роли

DELETE /api/access-control/roles/:uid?force=false

Удаляет роль с заданным UID и её права. Если роль назначена, операция удаления завершится ошибкой, если только параметр запроса force не установлен в true — в этом случае все назначения также будут удалены.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут удалить настраиваемую роль только с теми же правами или подмножеством прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет удалить настраиваемую роль, которая это позволяет.

Действие Область
roles:delete permissions:type:delegate

Пример запроса

http 
DELETE /api/access-control/roles/jZrmlLCGka?force=true&global=false
Accept: application/json

Параметры запроса

Параметр Тип Обязательно Описание
force boolean Нет Если установлено true, роль будет удалена вместе со всеми её назначениями.
global boolean Нет Флаг, указывающий, является ли роль глобальной. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя. Дополнительные сведения см. в разделе О RBAC.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role deleted"
}

Коды состояния

Код Описание
200 Роль удалена.
400 Некорректный запрос (неверный json, отсутствующий content-type, отсутствующие или недопустимые поля и т. д.).
403 Доступ запрещён
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Создание и удаление назначений ролей пользователям

Получение списка ролей, назначенных пользователю

GET /api/access-control/users/:userId/roles

Возвращает список ролей, которые были напрямую назначены заданному пользователю. Список не включает базовые роли (Viewer, Editor, Admin или Grafana Admin), а также роли, унаследованные от команды.

Параметры запроса:

  • includeHidden: необязательно. Установите true, чтобы включить роли, которые являются hidden.
  • includeMapped: необязательно. Установите true, чтобы включить роли, сопоставленные через функцию синхронизации атрибутов групп.

Требуемые права

Действие Область
users.roles:read users:id:<user ID>

Пример запроса

http 
GET /api/access-control/users/1/roles
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 4,
        "uid": "6dNwJq57z",
        "name": "fixed:reports:writer",
        "displayName": "Report writer",
        "description": "Create, read, update, or delete all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    }
]

Коды состояния

Код Описание
200 Набор назначенных ролей возвращён.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Получение своих прав

GET /api/access-control/user/permissions

Возвращает список прав, предоставленных авторизованному пользователю.

Требуемые права

Права не требуются.

Параметры запроса

Параметр Тип Обязательно Описание
reloadcache boolean Нет Флаг для перезагрузки кэша прав.

Пример запроса

http 
GET /api/access-control/user/permissions
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
  "dashboards:read": ["dashboards:uid:70KrY6IVz"],
  "dashboards:write": ["dashboards:uid:70KrY6IVz"],
  "datasources.id:read": ["datasources:*"],
  "datasources:read": ["datasources:*"],
  "datasources:explore": [""],
  "datasources:query": ["datasources:uid:grafana"],
  "datasources:read": ["datasources:uid:grafana"],
  "orgs:read": [""]
}

Коды состояния

Код Описание
200 Набор назначенных прав возвращён.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Получение списка прав, назначенных пользователю

GET /api/access-control/users/:userId/permissions

Возвращает список прав, предоставленных заданному пользователю.

Требуемые права

Действие Область
users.permissions:read users:id:<user ID>

Пример запроса

http 
GET /api/access-control/users/1/permissions
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "action": "ldap.status:read",
        "scope": ""
    },
    {
        "action": "ldap.user:read",
        "scope": ""
    }
]

Коды состояния

Код Описание
200 Набор назначенных прав возвращён.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Добавление назначения роли пользователю

POST /api/access-control/users/:userId/roles

Назначает роль конкретному пользователю.

Для массовых обновлений рассмотрите Установка назначений ролей пользователя.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут назначать только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет назначить роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
users.roles:add permissions:type:delegate

Пример запроса

http 
POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUid": "XvHQJq57z"
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
roleUid string Да UID роли.
global boolean Нет Флаг, указывающий, является ли назначение глобальным. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя для создания локального для организации назначения.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the user."
}

Коды состояния

Код Описание
200 Роль назначена пользователю.
403 Доступ запрещён.
404 Роль не найдена.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Удаление назначения роли пользователю

DELETE /api/access-control/users/:userId/roles/:roleUID

Отзывает роль у пользователя.

Для массовых обновлений рассмотрите Установка назначений ролей пользователя.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут снять только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет снять роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
users.roles:remove permissions:type:delegate

Параметры запроса

Параметр Тип Обязательно Описание
global boolean Нет Флаг, указывающий, является ли назначение глобальным. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя для удаления назначения.

Пример запроса

http 
DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role removed from user."
}

Коды состояния

Код Описание
200 Роль не назначена.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Установка назначений ролей пользователя

PUT /api/access-control/users/:userId/roles

Обновляет назначения ролей пользователя, приводя их в соответствие с предоставленным набором UID. Это удалит любые назначенные роли, которых нет в запросе, и добавит роли, которые есть в наборе, но ещё не назначены пользователю.

Если вы хотите добавить или удалить одну роль, рассмотрите использование Добавление назначения роли пользователю или Удаление назначения роли пользователю вместо этого.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут назначать или снимать только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет назначить или снять роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
users.roles:add permissions:type:delegate
users.roles:remove permissions:type:delegate

Пример запроса

http 
PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
global boolean Нет Флаг, указывающий, является ли назначение глобальным. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя.
roleUids list Да Список UID ролей.
includeHidden boolean Нет Указывает, следует ли обновлять назначения скрытых ролей.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "User roles have been updated."
}

Коды состояния

Код Описание
200 Роли назначены.
403 Доступ запрещён.
404 Роль не найдена.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Создание и удаление назначений ролей сервисным учётным записям

Получение списка ролей, назначенных сервисной учётной записи

GET /api/access-control/users/:serviceAccountId/roles

Возвращает список ролей, которые были напрямую назначены заданной сервисной учётной записи. Список не включает базовые роли (Viewer, Editor, Admin или Grafana Admin).

Параметры запроса:

  • includeHidden: необязательно. Установите true, чтобы включить роли, которые являются hidden.

Требуемые права

Действие Область
users.roles:read users:id:<service account ID>

Пример запроса

http 
GET /api/access-control/users/1/roles
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 4,
        "uid": "6dNwJq57z",
        "name": "fixed:reports:writer",
        "displayName": "Report writer",
        "description": "Create, read, update, or delete all reports and shared report settings.",
        "group": "Reports",
        "updated": "2021-11-19T10:48:00+01:00",
        "created": "2021-11-19T10:48:00+01:00",
        "global": false
    }
]

Коды состояния

Код Описание
200 Набор назначенных ролей возвращён.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Получение списка прав, назначенных сервисной учётной записи

GET /api/access-control/users/:serviceAccountId/permissions

Возвращает список прав, которые есть у заданной сервисной учётной записи.

Требуемые права

Действие Область
users.permissions:read users:id:<service account ID>

Пример запроса

http 
GET /api/access-control/users/1/permissions
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "action": "ldap.status:read",
        "scope": ""
    },
    {
        "action": "ldap.user:read",
        "scope": ""
    }
]

Коды состояния

Код Описание
200 Набор назначенных прав возвращён.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Добавление назначения роли сервисной учётной записи

POST /api/access-control/users/:serviceAccountId/roles

Назначает роль конкретной сервисной учётной записи.

Для массовых обновлений рассмотрите Установка назначений ролей сервисной учётной записи.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут назначать только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет назначить роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
users.roles:add permissions:type:delegate

Пример запроса

http 
POST /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUid": "XvHQJq57z"
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
roleUid string Да UID роли.
global boolean Нет Флаг, указывающий, является ли назначение глобальным. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя для создания локального для организации назначения.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the user."
}

Коды состояния

Код Описание
200 Роль назначена пользователю.
403 Доступ запрещён.
404 Роль не найдена.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Удаление назначения роли сервисной учётной записи

DELETE /api/access-control/users/:serviceAccountId/roles/:roleUID

Отзывает роль у сервисной учётной записи.

Для массовых обновлений рассмотрите Установка назначений ролей сервисной учётной записи.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут снять только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет снять роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
users.roles:remove permissions:type:delegate

Параметры запроса

Параметр Тип Обязательно Описание
global boolean Нет Флаг, указывающий, является ли назначение глобальным. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя для удаления назначения.

Пример запроса

http 
DELETE /api/access-control/users/1/roles/AFUXBHKnk
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role removed from user."
}

Коды состояния

Код Описание
200 Роль не назначена.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Установка назначений ролей сервисной учётной записи

PUT /api/access-control/users/:serviceAccountId/roles

Обновляет назначения ролей сервисной учётной записи, приводя их в соответствие с предоставленным набором UID. Это удалит любые назначенные роли, которых нет в запросе, и добавит роли, которые есть в наборе, но ещё не назначены сервисной учётной записи.

Если вы хотите добавить или удалить одну роль, рассмотрите использование Добавление назначения роли сервисной учётной записи или Удаление назначения роли сервисной учётной записи вместо этого.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут назначать или снимать только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет назначить или снять роль, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
users.roles:add permissions:type:delegate
users.roles:remove permissions:type:delegate

Пример запроса

http 
PUT /api/access-control/users/1/roles
Accept: application/json
Content-Type: application/json

{
    "global": false,
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
global boolean Нет Флаг, указывающий, является ли назначение глобальным. Если установлено false, из запроса будет использован ID организации по умолчанию аутентифицированного пользователя.
roleUids list Да Список UID ролей.
includeHidden boolean Нет Указывает, следует ли обновлять назначения скрытых ролей.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "User roles have been updated."
}

Коды состояния

Код Описание
200 Роли назначены.
403 Доступ запрещён.
404 Роль не найдена.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Создание и удаление назначений ролей командам

Получение списка ролей, назначенных команде

GET /api/access-control/teams/:teamId/roles

Возвращает список ролей, которые были напрямую назначены заданной команде.

Параметры запроса:

  • includeHidden: необязательно. Установите true, чтобы включить роли, которые являются hidden.

Требуемые права

Действие Область
teams.roles:read teams:id:<team ID>

Пример запроса

http 
GET /api/access-control/teams/1/roles
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

[
    {
        "version": 4,
        "uid": "j08ZBi-nk",
        "name": "fixed:licensing:reader",
        "displayName": "Licensing reader",
        "description": "Read licensing information and licensing reports.",
        "group": "Licenses",
        "updated": "2022-02-03T14:19:50+01:00",
        "created": "0001-01-01T00:00:00Z",
        "global": false
    }
]

Коды состояния

Код Описание
200 Набор назначенных ролей возвращён.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Добавление назначения роли команде

POST /api/access-control/teams/:teamId/roles

Назначает роль конкретной команде.

Для массовых обновлений рассмотрите Установка назначений ролей команды.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут назначать только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет прав, требуемых для создания пользователей, он не сможет назначить роль, содержащую эти права. Это сделано для предотвращения повышения привилегий.

Действие Область
teams.roles:add permissions:type:delegate

Пример запроса

http 
POST /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json

{
    "roleUid": "XvHQJq57z"
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
roleUid string Да UID роли.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role added to the team."
}

Коды состояния

Код Описание
200 Роль назначена команде.
403 Доступ запрещён.
404 Роль не найдена.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Удаление назначения роли команде

DELETE /api/access-control/teams/:teams/roles/:roleUID

Отзывает роль у команды.

Для массовых обновлений рассмотрите Установка назначений ролей команды.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут снять только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет прав, требуемых для создания пользователей, он не сможет назначить роль, содержащую эти права. Это сделано для предотвращения повышения привилегий.```

Действие Область
teams.roles:remove permissions:type:delegate

Пример запроса

http 
DELETE /api/access-control/teams/1/roles/AFUXBHKnk
Accept: application/json

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Role removed from team."
}

Коды состояния

Код Описание
200 Роль не назначена.
403 Доступ запрещён.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Установка назначений ролей команды

PUT /api/access-control/teams/:teamId/roles

Обновляет назначения ролей команды, приводя их в соответствие с предоставленным набором UID. Это удалит любые назначенные роли, которых нет в запросе, и добавит роли, которые есть в наборе, но ещё не назначены пользователю.

Если вы хотите добавить или удалить одну роль, рассмотрите использование Добавление назначения роли команде или Удаление назначения роли команде вместо этого.

Требуемые права

Область permissions:type:delegate гарантирует, что пользователи могут назначать или снимать только те роли, которые имеют те же права или подмножество прав, которые есть у пользователя. Например, если у пользователя нет требуемых прав на создание пользователей, он не сможет назначить или снять роль команде, которая это позволяет. Это сделано для предотвращения повышения привилегий.

Действие Область
teams.roles:add permissions:type:delegate
teams.roles:remove permissions:type:delegate

Пример запроса

http 
PUT /api/access-control/teams/1/roles
Accept: application/json
Content-Type: application/json

{
    "roleUids": [
        "ZiHQJq5nk",
        "GzNQ1357k"
    ]
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
roleUids list Да Список UID ролей.
includeHidden boolean Нет Указывает, следует ли обновлять назначения скрытых ролей.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Team roles have been updated."
}

Коды состояния

Код Описание
200 Роли назначены.
403 Доступ запрещён.
404 Роль не найдена.
500 Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

Сброс базовых ролей к значениям по умолчанию

POST /api/access-control/roles/hard-reset

Область permissions:type:escalate позволяет пользователям сбрасывать права базовых ролей. Это может привести к тому, что базовые роли будут иметь права, превышающие права вызывающего пользователя.

Сбрасывает права базовых ролей к значениям по умолчанию.

Требуемые права

Действие Область
roles:write permissions:type:escalate

Пример запроса

http 
POST /api/access-control/roles/hard-reset
Accept: application/json
Content-Type: application/json

{
    "BasicRoles": true
}

Схема тела JSON

Имя поля Тип данных Обязательно Описание
BasicRoles boolean Нет Опция для сброса прав базовых ролей.

Пример ответа

http 
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8

{
    "message": "Reset performed"
}

Коды состояния

Код Описание
200 Сброс выполнен
500 Не удалось сбросить базовые роли