문서로 건너뛰기
SDK

역할

`roles.list`, `get`, `create`, `update`, `delete`, `listPermissions`.

모든 메서드

roles.ts
const roles = await openemail.roles.list()const role = await openemail.roles.get('role_…') const support = await openemail.roles.create({  name: 'Support',  description: 'Answers the shared inboxes and nothing else.',  permissions: ['emails:send', 'threads:write', 'labels:write'],}) console.log(support.permissions) await openemail.roles.update(support.id, {  permissions: [...support.permissions, 'templates:read'],}) await openemail.roles.delete(support.id, { reassignTo: 'role_…' }) const vocabulary = await openemail.roles.listPermissions()

support.permissions에는 세 개가 아니라 여섯 개가 들어 있습니다. emails:sendemails:read를, threads:writethreads:read를, labels:writelabels:read를 함께 가져옵니다. 짐작하지 말고 목록을 다시 읽으십시오.

역할은 그 사람이 무엇을 해도 되는지를 말합니다. 어떤 주소에 대해 할 수 있는지는 다른 축이며 openemail.members에 있습니다. 그쪽의 grantAddressrevokeAddress를 참고하십시오. “메일을 보낼 수 있다”와 “invoices@로 보낼 수 있다”는 서로 다른 문장이며, 지원 담당을 한 명 더 채용한 워크스페이스는 앞의 것은 건드리지 않고 뒤의 것만 바꿉니다.

builtin의 이름이 아니라 editabledeletable로 분기하십시오. 둘 다 false인 것은 소유자 역할뿐이며, 그 권한 목록은 “내년에 새로 생길 것까지 포함한 모든 권한”으로 저장되는 대신 계산됩니다. 워크스페이스에 기본 제공되는 다섯 개를 포함해 나머지 역할은 모두 두 값이 true입니다. 누군가 이름을 바꾼 역할도 두 값은 정확히 답하지만, 그 이름은 더 이상 아무것도 알려 주지 않습니다.

update는 권한 목록을 통째로 교체합니다. 권한 하나만 부여하는 호출은 없으므로, 역할을 읽어서 의도한 항목만 바꾼 뒤 전체를 다시 보내십시오. 권한 하나만 보내면 그 역할에는 그 하나와 그것이 함축하는 권한만 남습니다.

누군가 그 역할을 갖고 있는 순간부터 delete에는 reassignTo가 필요하며, 이 값은 쿼리 파라미터로 전달됩니다. DELETE의 본문은 여러 런타임과 적지 않은 프록시가 버리기 때문입니다. 결과는 reassignedkeysReassigned를 따로 보고하므로, 스크립트가 요청한 내용이 아니라 실제로 수행한 내용을 기록할 수 있습니다.

listPermissions()는 역할 id가 들어갈 자리에 그대로 놓인 고정 경로인 GET /roles/permissions입니다. 클라이언트는 이 문자열을 get에 흘려보내지 않고 하드코딩하므로, 이름이 정말로 “permissions”인 역할을 요청하면 역할을 요청한 것이 되어 404를 받습니다. 그것이 입력한 내용에 대한 정직한 답입니다. scope: false는 어떤 키도 결코 가질 수 없는 항목을 표시합니다.

역할은 키의 상한이다

역할에 묶여 발급된 키는 자신의 스코프와 그 역할의 권한을 교집합한 만큼만 할 수 있으며, 이는 요청마다 경계에서 계산됩니다. 따라서 역할을 좁히면 키를 하나도 회전하지 않고도 그 키들의 권한이 즉시 회수되고, 역할이 없는 키에는 상한이 전혀 없습니다. 즉 null인 역할은 키가 가질 수 있는 가장 좁은 상태가 아니라 가장 넓은 상태입니다.

roles.delete가 키를 옮길 곳을 반드시 요구하는 이유도 같습니다. 키를 고아로 남기면 상한이 통째로 사라져, 그 역할이 제한하고 있던 모든 자격 증명이 조용히 승격됩니다.

GET /keys/selfGET /ping은 실제 적용되는 scopes 옆에 roleIdgrantedScopes를 함께 보고하며, “내 키에는 emails:send가 있는데 insufficient_scope가 납니다”라는 질문은 이렇게 답합니다. grantedScopes에는 있는데 scopes에는 없는 것은 역할이 걷어낸 것입니다. openemail.me.get()openemail.me.ping()이 둘 다 타입과 함께 반환합니다.

파라미터

namestring필수
워크스페이스가 이 역할을 부르는 이름이며, 1자에서 48자이고 저장 전에 앞뒤 공백을 제거합니다. 이름은 워크스페이스 안에서 대소문자를 구분하지 않고 고유해야 하므로, 두 번째 “Support”는 첫 번째 옆에 새로 만들어지지 않고 `role_name_taken`(409)으로 거부됩니다.
descriptionstring
역할의 용도를 설명하는 한 문장이며, 앞뒤 공백을 제거하고 최대 240자입니다. 공백을 제거했을 때 비어 있는 문자열은 null로 저장되므로, 공백으로만 된 설명은 보낸 그대로가 아니라 null로 돌아옵니다.
permissionsPermission[]필수
역할이 부여하는 권한이며, `listPermissions()`가 제공하는 어휘에서 가져옵니다. 거기에 없는 문자열은 조용히 버려지지 않고 `permissions`에 대한 422가 되므로, 오타 하나로 오후를 통째로 날리는 대신 바로 보고받습니다. 목록은 들어올 때 확장되고(`templates:write`는 `templates:read`도 함께 저장합니다), 중복이 제거되며, 정해진 순서로 재배열됩니다. 따라서 보낸 목록이 그대로라고 가정하지 말고 응답에서 저장된 목록을 읽으십시오.

응답

object'role'
항상 `role`입니다. 삭제 시의 묘비 응답도 같은 값과 함께 역할의 `id`, `deleted: true`, 두 가지 재할당 개수만 돌려주고, 아래의 다른 필드는 돌려주지 않습니다.
idstring
역할의 id입니다. 멤버의 `roleId`가 가리키는 값이자, API 키의 상한이 가리키는 값이며, 이 역할을 삭제할 때 `reassignTo`가 받는 값입니다.
namestring
워크스페이스가 이 역할에 붙인 이름이며, 앞뒤 공백을 제거하고 대소문자를 구분하지 않고 고유합니다. 소유자 역할을 제외한 모든 역할은 기본 제공된 것을 포함해 이름을 바꿀 수 있으므로(`builtin`은 그 행이 어디서 왔는지를 말할 뿐, 계속 그 이름이어야 한다는 뜻이 아닙니다), “Admin”이라는 이름을 그 역할이 무엇을 가졌는지에 대한 약속으로 읽지 마십시오. 다른 역할이 이미 쓰고 있는 이름은 `role_name_taken`(409, `param: "name"`)이고, 소유자 역할의 이름을 바꾸는 것은 그 역할의 다른 모든 수정과 마찬가지로 `role_immutable`(409)입니다.
descriptionstring | null
역할을 설명하는 문장이며, 주어지지 않았으면 null입니다. 생성과 수정 모두에서 빈 입력은 null로 저장되므로, 이 값이 빈 문자열이 되는 일은 없습니다.
permissionsPermission[]
역할이 부여하는 모든 권한이며, 누가 입력한 순서가 아니라 이미 확장되어 정해진 순서로 정렬된 상태입니다. 이 정렬은 중요한 역할을 합니다. 같은 권한을 가진 두 역할은 JSON으로 비교했을 때 동일해지고, 덕분에 설정 화면이 둘을 비교해 저장 버튼을 켤지 말지 결정할 수 있습니다.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null
이 행이 기본 제공되는 여섯 역할 중 어디에서 왔는지이며, 워크스페이스가 직접 만든 역할이면 null입니다. 상태가 아니라 출처를 기록할 뿐입니다. 기본 제공 역할도 다른 역할과 똑같이 이름을 바꾸고 권한을 바꾸고 삭제할 수 있습니다. 이 값이 아니라 `editable`과 `deletable`로 분기하십시오. 누군가 “Admin”이라고 부르는 역할이 기본 제공 역할이 아닐 수 있고, 기본 제공 역할이 더 이상 그 이름이 아닐 수도 있습니다.
editableboolean
`builtin !== 'owner'`로 계산되므로 소유자 역할에서만 false이며, 그 역할에 대한 PATCH는 모두 `role_immutable`(409)로 거부됩니다. 워크스페이스에 기본 제공되는 다섯 개를 포함한 나머지 역할은 이름, 설명, 권한까지 전부 수정할 수 있습니다.
deletableboolean
`builtin !== 'owner'`로 계산됩니다. 소유자 역할에서만 false이며 그 경우 `role_undeletable`(409)로 돌아오고, 기본 제공 역할을 포함한 나머지 역할에서는 true입니다. 거부당한 뒤가 아니라 버튼을 보여 주기 전에 확인하십시오. 다만 아직 누군가 갖고 있는 역할에는 `reassignTo`도 필요하며, 없으면 삭제는 `role_in_use`(409)입니다.
membersnumber
이 역할을 가진 사람 수이며, 워크스페이스의 멤버 행에서 셉니다. 소유자는 여기에 포함되지 않습니다. 소유자는 멤버 행이 없고 역할을 부여받을 수도 없으므로, 멤버 목록에는 소유자가 보이더라도 Owner 역할의 보유자 수는 0으로 보고됩니다.
apiKeysnumber
이 역할이 상한을 두고 있는 유효한 API 키 수입니다. 폐기된 키는 이 수에서 제외되지만, 삭제 시에는 폐기된 키를 포함해 이 역할을 가리키는 모든 키 행이 다시 연결됩니다. 역할을 없애기 전에 옮겨야 하는 두 번째 집단이자 아무도 알아채지 못하는 집단입니다. 키는 프로그램이고, 프로그램은 불평하지 않으니까요.
createdAtstring
역할 행이 기록된 시각이며 ISO-8601입니다. 내장 역할 행은 워크스페이스를 만들 때가 아니라, 역할 목록 조회나 역할 생성, API 키 화면처럼 무언가 필요로 하는 순간 처음으로 지연 생성됩니다. 그래서 내장 역할의 타임스탬프는 워크스페이스가 만들어진 때가 아니라 그 첫 요청이 들어온 때입니다.
updatedAtstring
역할이 마지막으로 변경된 시각이며 ISO-8601입니다. 이미 갖고 있던 값을 그대로 설정하는 PATCH를 포함해, 수락된 모든 PATCH가 이 값을 갱신합니다.