역할 만들기
이름 하나와 권한 목록 하나. 돌아오는 것은 보낸 것보다 깁니다.
본인 키로 워크스페이스에 실제 호출을 실행합니다.
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}이고, 키를 그 역할로 지정하는 것은 키를 발급하는 곳에서 합니다.