Rollen
`roles.list`, `get`, `create`, `update`, `delete` en `listPermissions`.
Elke methode
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 bevat zes items, geen drie: emails:send brengt emails:read mee, threads:write brengt threads:read mee en labels:write brengt labels:read mee. Lees de lijst terug in plaats van hem aan te nemen.
Een rol zegt wat iemand MAG DOEN. Op welke ADRESSEN ze dat mogen doen is de andere as en die zit op openemail.members. Zie daar grantAddress en revokeAddress. “Mag mail versturen” en “mag versturen als invoices@” zijn verschillende zinnen, en een workspace die een tweede supportmedewerker aanneemt, verandert de tweede zonder de eerste aan te raken.
Vertak op editable en deletable in plaats van op de naam in builtin. Beide zijn alleen false voor de eigenaar, wiens lijst “elke permissie, inclusief de permissies die volgend jaar bedacht worden” is en berekend wordt in plaats van opgeslagen; elke andere rol antwoordt op beide true, inclusief de vijf die een workspace bij aanmaak krijgt. Een rol die iemand hernoemd heeft, antwoordt nog steeds op beide correct, en de naam ervan zegt je niets meer.
update VERVANGT de permissielijst. Er is geen aanroep om er één toe te kennen, dus lees de rol, wijzig het item dat je bedoelde en stuur ze allemaal terug. Eén permissie sturen laat de rol met precies die ene achter, plus alles wat die impliceert.
delete heeft reassignTo nodig zodra iemand de rol heeft, en die reist mee als query parameter omdat een body op DELETE door verschillende runtimes en een aantal proxy's wordt weggegooid. Het resultaat meldt reassigned en keysReassigned apart, zodat een script kan loggen wat het gedaan heeft in plaats van wat het gevraagd heeft.
listPermissions() is GET /roles/permissions, een vast pad dat precies staat waar een role id zou staan. De client codeert dat hard in plaats van de string door get te sturen, dus vragen om een rol die werkelijk “permissions” heet, vraagt om een rol en krijgt een 404, wat het eerlijke antwoord is op wat er getypt is. scope: false markeert de items die geen enkele key ooit kan hebben.
Een rol is het plafond op een key
Een key die op een rol is uitgegeven, mag zijn eigen scopes DOORSNEDEN met de permissies van die rol, per verzoek aan de rand bepaald. Een rol versmallen trekt zijn keys dus live in, zonder dat er ook maar één geroteerd wordt, en een key zonder rol heeft helemaal geen plafond, waardoor een null rol de ruimste stand is waarin een key kan staan, niet de smalste.
Daarom eist roles.delete ook een plek om de keys naartoe te verplaatsen. Ze wees achterlaten zou hun plafond helemaal weghalen, en stilletjes elke credential promoveren die de rol aan banden hield.
GET /keys/self en GET /ping melden roleId en grantedScopes naast de effectieve scopes, en zo wordt “mijn key heeft emails:send en ik krijg insufficient_scope” beantwoord: alles wat in grantedScopes staat en in scopes ontbreekt, is door de rol weggenomen. openemail.me.get() en openemail.me.ping() geven ze allebei terug, getypeerd.
Parameters
namestringverplicht- Hoe de workspace de rol noemt: 1 tot 48 tekens, getrimd voordat hij wordt opgeslagen. Namen zijn per workspace uniek, hoofdletterongevoelig, dus een tweede "Support" wordt geweigerd met `role_name_taken` (409) in plaats van naast de eerste aangemaakt.
descriptionstring- Een zin die zegt waar de rol voor is, getrimd en maximaal 240 tekens. Een string die na trimmen leeg is, wordt als null opgeslagen, dus een beschrijving van spaties komt terug als null en niet als wat je stuurde.
permissionsPermission[]verplicht- Wat de rol toekent, uit de woordenlijst die `listPermissions()` serveert; een string die daar niet in staat is een 422 op `permissions` in plaats van dat hij stilletjes wordt weggelaten, zodat een typefout gemeld wordt in plaats van je een middag te kosten. De lijst wordt bij binnenkomst UITGEBREID (`templates:write` slaat `templates:read` ernaast op), ontdubbeld en in canonieke volgorde teruggezet, dus lees de opgeslagen lijst uit de response in plaats van aan te nemen dat het de lijst is die je stuurde.
Respons
object'role'- Altijd `role`. De tombstone van een delete antwoordt met dezelfde waarde, de `id` van de rol, `deleted: true` en de twee hertoewijzingsaantallen, en met geen van de andere velden hieronder.
idstring- De id van de rol. Het is waar de `roleId` van een lid naar verwijst, waar het plafond van een API key naar wijst, en wat `reassignTo` aanneemt wanneer deze rol verwijderd wordt.
namestring- De naam die de workspace aan de rol geeft, getrimd en hoofdletterongevoelig uniek. Elke rol behalve die van de eigenaar kan hernoemd worden, de geseede rollen inbegrepen (`builtin` zegt waar een rij vandaan komt, niet hoe die moet blijven heten), dus lees "Admin" niet als een belofte over wat de rol bevat. Een naam waarop een andere rol al luistert is `role_name_taken` (409, `param: "name"`); de eigenaar hernoemen is `role_immutable` (409), net als elke andere bewerking ervan.
descriptionstring | null- De zin die de rol beschrijft, of null wanneer er geen is opgegeven. Lege invoer wordt bij zowel create als update als null opgeslagen, dus dit is nooit een lege string.
permissionsPermission[]- Alles wat de rol toekent, al uitgebreid en in canonieke volgorde in plaats van in de volgorde die iemand intypte. Die volgorde is dragend: twee rollen met dezelfde permissies zijn als JSON aan elkaar gelijk, en dat is wat een instellingenscherm in staat stelt ze te vergelijken om te bepalen of Opslaan aan staat.
builtin'owner' | 'admin' | 'member' | 'viewer' | 'developer' | 'billing' | null- Uit welke van de zes geseede rollen deze rij komt, of null voor een rol die de workspace zelf geschreven heeft. Het legt de herkomst vast en geen status: een geseede rol wordt hernoemd, van andere permissies voorzien en verwijderd als elke andere. Vertak op `editable` en `deletable` in plaats van hierop. Een rol die iemand "Admin" noemde hoeft niet de geseede rol te zijn, en de geseede rol heet misschien niet meer zo.
editableboolean- Berekend als `builtin !== 'owner'`, dus alleen voor de eigenaarsrol is hij false en elke PATCH van die rol wordt geweigerd met `role_immutable` (409). Elke andere rol is volledig bewerkbaar (naam, beschrijving en permissies), inclusief de vijf waarmee een workspace geseed wordt.
deletableboolean- Berekend als `builtin !== 'owner'`: alleen false voor de eigenaarsrol, die terugkomt met `role_undeletable` (409), en true voor elke andere rol, de geseede inbegrepen. Controleer hem voordat je de knop aanbiedt in plaats van na de weigering, al heeft een rol die iemand nog heeft ook `reassignTo` nodig, anders is de delete `role_in_use` (409).
membersnumber- Hoeveel mensen deze rol hebben, geteld uit de ledenrijen van de workspace. De eigenaar hoort daar niet bij: die heeft geen ledenrij en kan geen rol krijgen, dus de rol van de eigenaar meldt nul houders, ook al staat de eigenaar wel in de ledenlijst.
apiKeysnumber- Hoeveel actieve API keys door deze rol begrensd worden; ingetrokken keys tellen niet mee, al wijst een delete elke keyrij die naar de rol wijst opnieuw toe, de ingetrokken inbegrepen. Het is de tweede populatie die verplaatst moet worden voordat de rol weg kan, en degene die niemand opmerkt: keys zijn programma's, en een programma klaagt niet.
createdAtstring- Wanneer de rij van de rol is weggeschreven, ISO-8601. Ingebouwde rijen worden lui aangemaakt op het moment dat iets ze voor het eerst nodig heeft, zoals het lezen van een rollenlijst, het aanmaken van een rol of het API-key-scherm, en niet bij het aanmaken van de workspace, dus de timestamp van een ingebouwde rol is wanneer dat eerste verzoek binnenkwam en niet wanneer de workspace gemaakt is.
updatedAtstring- Wanneer de rol voor het laatst is gewijzigd, ISO-8601. Elke geaccepteerde PATCH verzet hem, ook een die een veld zet op de waarde die het al had.