SDK

Rollen

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

Alle Methoden

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 enthält sechs Einträge, nicht drei: emails:send bringt emails:read mit, threads:write bringt threads:read mit und labels:write bringt labels:read mit. Die Liste sollte zurückgelesen und nicht angenommen werden.

Eine Rolle sagt, was jemand TUN darf. Auf welche ADRESSEN sich das bezieht, ist die andere Achse und liegt auf openemail.members. Siehe dort grantAddress und revokeAddress. „Darf Mail senden“ und „darf als invoices@ senden“ sind zwei verschiedene Sätze, und ein Workspace, der eine zweite Support-Kraft einstellt, ändert den zweiten, ohne den ersten anzurühren.

Die Verzweigung sollte über editable und deletable erfolgen und nicht über den Namen von builtin. Beide sind allein für die Owner-Rolle false, deren Liste „jede Berechtigung, einschließlich der erst nächstes Jahr erfundenen“ lautet und die berechnet statt gespeichert wird; jede andere Rolle antwortet auf beide mit true, einschließlich der fünf, mit denen ein Workspace initial bestückt wird. Eine von jemandem umbenannte Rolle beantwortet beide weiterhin korrekt, und ihr Name sagt nichts mehr aus.

update ERSETZT die Berechtigungsliste. Es gibt keinen Aufruf, der eine einzelne Berechtigung vergibt; daher muss die Rolle gelesen, der gemeinte Eintrag geändert und alle Berechtigungen zurückgesendet werden. Wird eine einzige Berechtigung gesendet, hält die Rolle danach genau diese eine, zuzüglich dessen, was sie impliziert.

delete benötigt reassignTo, sobald irgendjemand die Rolle innehat, und der Wert reist als Query-Parameter, weil ein Body bei DELETE von mehreren Runtimes und etlichen Proxys verworfen wird. Das Ergebnis meldet reassigned und keysReassigned getrennt, sodass ein Skript protokollieren kann, was es getan hat, und nicht, was es angefordert hat.

listPermissions() ist GET /roles/permissions, ein fester Pfad, der genau dort sitzt, wo eine Rollen-id stünde. Der Client kodiert ihn fest, statt den String durch get zu reichen; die Abfrage nach einer Rolle, die tatsächlich „permissions“ heißt, fragt also nach einer Rolle und erhält ein 404, was die ehrliche Antwort auf das Getippte ist. scope: false kennzeichnet die Einträge, die kein Key jemals halten kann.

Eine Rolle ist die Obergrenze für einen Key

Ein gegen eine Rolle ausgestellter Key darf das, was der Schnitt aus seinen eigenen Scopes und den Berechtigungen dieser Rolle ergibt, aufgelöst pro Anfrage an der Grenze. Eine Rolle einzuschränken entzieht ihren Keys also live Rechte, ohne dass einer von ihnen rotiert wird, und ein Key ohne Rolle hat überhaupt keine Obergrenze – womit eine null-Rolle der weiteste Zustand ist, in dem ein Key sein kann, und nicht der engste.

Das ist auch der Grund, warum roles.delete darauf besteht, dass es ein Ziel gibt, an das die Keys verschoben werden. Sie verwaist zurückzulassen würde ihre Obergrenze vollständig entfernen und damit stillschweigend jedes Credential heraufstufen, das die Rolle gedeckelt hat.

GET /keys/self und GET /ping melden roleId und grantedScopes neben den effektiven scopes; so wird „mein Key hat emails:send und ich bekomme insufficient_scope“ beantwortet: Alles, was in grantedScopes steht und in scopes fehlt, hat die Rolle genommen. openemail.me.get() und openemail.me.ping() geben beides typisiert zurück.

Parameter

namestringerforderlich: Wie der Workspace die Rolle nennt: 1 bis 48 Zeichen, vor dem Speichern getrimmt. Namen sind pro Workspace ohne Beachtung der Groß-/Kleinschreibung eindeutig; ein zweites „Support“ wird daher mit `role_name_taken` (409) abgelehnt, statt neben dem ersten angelegt zu werden.
descriptionstring: Ein Satz, der beschreibt, wozu die Rolle da ist; getrimmt und höchstens 240 Zeichen. Ein String, der nach dem Trimmen leer ist, wird als null gespeichert; eine Beschreibung aus Leerzeichen kommt also als null zurück und nicht als das Gesendete.
permissionsPermission[]erforderlich: Was die Rolle gewährt, entnommen dem Vokabular, das `listPermissions()` ausliefert; ein String, der nicht darin enthalten ist, ergibt ein 422 auf `permissions` und wird nicht stillschweigend verworfen, sodass ein Tippfehler gemeldet wird, statt einen Nachmittag zu kosten. Die Liste wird beim Eingang AUFGEWEITET (`templates:write` speichert `templates:read` daneben), dedupliziert und in die kanonische Reihenfolge gebracht; die gespeicherte Liste sollte daher aus der Antwort gelesen werden, statt anzunehmen, dass sie der gesendeten entspricht.

Antwort

object'role': Immer `role`. Der Tombstone beim Löschen antwortet mit demselben Wert, der `id` der Rolle, `deleted: true` und den beiden Umhängungszählern – und mit keinem der übrigen Felder unten.
idstring: Die id der Rolle. Sie ist das, was der `roleId` eines Mitglieds benennt, worauf die Obergrenze eines API-Keys zeigt und was `reassignTo` entgegennimmt, wenn diese Rolle gelöscht wird.
namestring: Der Name, den der Workspace der Rolle gibt, getrimmt und ohne Beachtung der Groß-/Kleinschreibung eindeutig. Jede Rolle außer der des Owners kann umbenannt werden, die initial angelegten eingeschlossen (`builtin` sagt, woher eine Zeile stammt, nicht, wie sie heißen muss); „Admin“ sollte daher nicht als Versprechen darüber gelesen werden, was die Rolle hält. Ein Name, auf den bereits eine andere Rolle hört, ist `role_name_taken` (409, `param: "name"`); das Umbenennen der Owner-Rolle ist `role_immutable` (409), wie jede andere Bearbeitung an ihr.
descriptionstring | null: Der Satz, der die Rolle beschreibt, oder null, wenn keiner angegeben wurde. Leere Eingaben werden sowohl bei create als auch bei update als null gespeichert; dieses Feld ist daher nie ein leerer String.
permissionsPermission[]: Alles, was die Rolle gewährt, bereits aufgeweitet und in kanonischer Reihenfolge statt in der Reihenfolge, in der es jemand getippt hat. Diese Ordnung ist tragend: Zwei Rollen mit denselben Berechtigungen sind als JSON gleich, und genau das erlaubt es einem Einstellungsbildschirm, sie zu vergleichen und daraus abzuleiten, ob „Speichern“ aktiv ist.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null: Aus welcher der sechs initial angelegten Rollen diese Zeile stammt, oder null bei einer, die der Workspace selbst geschrieben hat. Festgehalten wird die Herkunft, kein Status: Eine initial angelegte Rolle wird wie jede andere umbenannt, neu berechtigt und gelöscht. Die Verzweigung sollte über `editable` und `deletable` erfolgen und nicht hierüber. Eine Rolle, die jemand „Admin“ genannt hat, muss nicht die initial angelegte sein, und die initial angelegte heißt vielleicht längst anders.
editableboolean: Berechnet als `builtin !== 'owner'`, also allein für die Owner-Rolle false; jedes PATCH auf diese Rolle wird mit `role_immutable` (409) abgelehnt. Jede andere Rolle ist vollständig bearbeitbar (Name, Beschreibung und Berechtigungen), einschließlich der fünf, mit denen ein Workspace initial bestückt wird.
deletableboolean: Berechnet als `builtin !== 'owner'`: false allein für die Owner-Rolle, die mit `role_undeletable` (409) zurückkommt, und true für jede andere Rolle, die initial angelegten eingeschlossen. Das Feld sollte geprüft werden, bevor der Button angeboten wird, und nicht erst nach der Ablehnung; eine Rolle, die jemand noch innehat, braucht zusätzlich `reassignTo`, sonst ist das Löschen `role_in_use` (409).
membersnumber: Wie viele Personen diese Rolle innehaben, gezählt aus den Mitgliederzeilen des Workspace. Der Owner zählt nicht dazu: Er hat keine Mitgliederzeile und kann keine Rolle erhalten, daher meldet die Owner-Rolle null Inhaber, obwohl die Mitgliederliste ihn anzeigt.
apiKeysnumber: Wie viele aktive API-Keys durch diese Rolle gedeckelt sind; widerrufene Keys bleiben in der Zählung unberücksichtigt, obwohl ein Löschen jede Key-Zeile umhängt, die auf die Rolle zeigt – die widerrufenen eingeschlossen. Das ist die zweite Population, die verschoben werden muss, bevor die Rolle gehen kann, und die, die niemand bemerkt: Keys sind Programme, und ein Programm beschwert sich nicht.
createdAtstring: Wann die Zeile der Rolle geschrieben wurde, ISO-8601. Eingebaute Zeilen werden verzögert angelegt, sobald etwas sie erstmals benötigt – etwa das Lesen einer Rollenliste, das Anlegen einer Rolle oder der API-Key-Bildschirm –, und nicht bei der Erstellung des Workspace; der Zeitstempel einer eingebauten Rolle ist also der Zeitpunkt, an dem diese erste Anfrage eintraf, und nicht der, an dem der Workspace angelegt wurde.
updatedAtstring: Wann sich die Rolle zuletzt geändert hat, ISO-8601. Jedes akzeptierte PATCH bewegt den Wert, auch eines, das ein Feld auf den bereits gehaltenen Wert setzt.