Создать роль
Имя и список разрешений. Обратно приходит больше, чем вы отправили.
Выполняет настоящий запрос в вашем рабочем пространстве, с вашим собственным ключом.
POST /roles
Имя и список разрешений. Обратно приходит больше, чем вы отправили.
Пример
Требует roles:write. Возвращает 201. Пользовательская роль имеет builtin: null, editable: true и deletable: true, и её никто не держит, пока на неё кого-нибудь не переведут.
curl -X POST "$OE/roles" -H "$AUTH" -H "Content-Type: application/json" \ -d '{ "name": "Support", "description": "Answers the shared inboxes and nothing else.", "permissions": ["emails:send", "threads:write", "labels:write", "contacts:read"] }'{ "object": "role", "id": "role_2b81de079c1f0a4b7e05d386", "name": "Support", "description": "Answers the shared inboxes and nothing else.", "permissions": [ "emails:send", "emails:read", "threads:read", "threads:write", "labels:read", "labels:write", "contacts:read" ], "builtin": null, "editable": true, "deletable": true, "members": 0, "apiKeys": 0, "createdAt": "2026-08-30T10:41:02.000Z", "updatedAt": "2026-08-30T10:41:02.000Z"}Ушло четыре разрешения, вернулось семь. emails:send подразумевает emails:read, threads:write подразумевает threads:read, labels:write подразумевает labels:read. Роль, которая может заархивировать цепочку, но не может её открыть, — это забытая галочка, а не чья-то осознанная политика, поэтому следствие сохраняется, а не отклоняется. Список также возвращается в каноническом порядке, и именно это позволяет клиенту сравнить две роли как JSON и решить, активна ли кнопка сохранения.
Неизвестное разрешение здесь ОТКЛОНЯЕТСЯ, а не отбрасывается: templates:writ — это invalid_parameter, 422, с указанием строки. Сервис нормализует молча, потому что он же обслуживает путь начального заполнения и путь MCP, где проваливать целую роль из-за одного неопознанного слова было бы хуже. На вызове, сделанном человеком осознанно, это неправильно. Ответ 200 с ролью, которая не может редактировать шаблоны, не сообщил ему ничего, и он потратит на это полдня.
Дублирующееся имя в том же рабочем пространстве — это role_name_taken, 409. 25-я пользовательская роль — это role_limit_reached, 422. Это ограничение на то, насколько большой может стать матрица, прежде чем её перестанут проверять, и это не граница тарифа.
Создание роли не даёт её никому. Перевод людей на неё — это PATCH /members/{userId}, а привязка ключа к ней делается там, где выпускается ключ.