Rollen opsommen
Elke rol in de workspace, ingebouwde rollen eerst, met hoeveel mensen en keys elke rol hebben.
Voert de echte aanroep uit op je workspace, met je eigen sleutel.
GET /roles
Elke rol in de workspace, ingebouwde rollen eerst, met hoeveel mensen en keys elke rol hebben.
Twee assen, en het zijn niet dezelfde vraag
export OE=https://api.openemail.ukexport AUTH="Authorization: Bearer $OPENEMAIL_API_KEY"Een ROL zegt wat iemand in deze workspace mag DOEN: mail lezen, mail versturen, templates bewerken, een domein toevoegen. Een TOEKENNING zegt op welke ADRESSEN dat mag, en staat ernaast op /members/{userId}/addresses als member (leest het adres en verstuurt eronder) of viewer (leest het alleen). Beide moeten het eens zijn voordat er een bericht uitgaat: een rol met emails:send en zonder toekenningen kan vanaf niets versturen, en elk adres in de workspace onder een viewer-toekenning kan evenmin ergens vandaan versturen.
Elke workspace wordt aangelegd met dezelfde zes rollen. Owner, Admin, Member en Viewer vormen een ladder. Elke rol heeft alles wat de volgende heeft, dus iemand degraderen versmalt zijn toegang in plaats van die te vervangen door een ander stuk. Developer en Billing zijn geen sporten van die ladder: Developer bouwt integraties (keys, webhooks, templates, versturen) en leest geen enkele mail van de workspace, en Billing ziet het abonnement en de facturen en verder niets. Beide vallen strikt binnen Admin. Ze worden bij de eerste leesactie aangelegd en niet bij het aanmaken van de workspace, dus een workspace van vóór deze functie krijgt ze zodra er iets om vraagt. builtin noemt uit welke seed een rij komt, en dat is alles wat het noemt: de zes zijn een startpunt dat een workspace hoort bij te schaven, en op Owner na kan elk ervan hernoemd, van andere permissies voorzien en verwijderd worden. Vertak op editable en deletable en niet op de naam: een rol die iemand hernoemd heeft, beantwoordt die twee nog steeds correct, en zijn naam zegt je niets meer.
Owner is de enige uitzondering, en dat in alle richtingen: editable: false, deletable: false, en geweigerd als doel bij PATCH /members/{userId}. Hij beschrijft het account waar de workspace aan hangt en heeft elke permissie, inclusief permissies die in een latere release zijn toegevoegd — daarom wordt zijn lijst berekend in plaats van opgeslagen. Iemand anders eigenaar maken is een overdracht van de workspace; er is hier geen endpoint dat dat uitvoert.
De andere vijf accepteren alles: een nieuwe permissielijst, een nieuwe beschrijving, een nieuwe naam, een DELETE. Het zijn voorgeprogrammeerde standaarden en geen vaste inventaris: een workspace die nooit een integratie bouwt, moet van Developer af kunnen, en een workspace waar "Member" iets smallers betekent, moet dat in eigen woorden kunnen zeggen. Alleen de owner weigert, en die weigert het hele stel onder één code: role_immutable, een 409 met param: "roleId", of de PATCH nu een naam of een permissielijst bevatte. Een hernoeming wordt niet langer apart geweigerd, dus er is geen onveranderlijkheid met param: "name" om af te handelen; de enige 409 die een naam nog kan opleveren is role_name_taken, wanneer een andere rol in de workspace al zo heet.
Boven op die zes schrijft een workspace tot 24 eigen rollen. Het plafond telt alleen die, dus een aangelegde standaardrol verwijderen levert er geen ruimte onder op. Permissies worden bij binnenkomst UITGEKLAPT in plaats van letterlijk genomen (templates:write alleen wordt opgeslagen als templates:read en templates:write), dus lees de lijst terug uit het antwoord in plaats van aan te nemen dat het de lijst is die je verstuurde.
Een rol is ook het plafond van een API key. Een key die onder een rol is uitgegeven mag key.scopes ∩ role.permissions en niets meer, per request aan de rand bepaald, dus een rol bewerken verandert wat zijn keys mogen bij hun eerstvolgende aanroep, en een key zonder rol heeft helemaal geen plafond. De pagina Scopes behandelt dat volledig.
Voorbeeld
Vereist roles:read. Zonder cursor. De envelop bevat hasMore en nextCursor zodat een client hem aan dezelfde lijstcode kan geven als elke andere collectie, en er is nooit een tweede pagina.
curl "$OE/roles" -H "$AUTH"{ "object": "list", "data": [ { "object": "role", "id": "role_1c94e05d3862c1f0a44b7f3a", "name": "Owner", "description": "The person the workspace belongs to. Holds everything, including additions.", "permissions": ["emails:send", "emails:read", "…", "workspace:manage"], "builtin": "owner", "editable": false, "deletable": false, "members": 0, "apiKeys": 2, "createdAt": "2026-08-01T09:00:00.000Z", "updatedAt": "2026-08-01T09:00:00.000Z" }, { "object": "role", "id": "role_c40a95f21cc65d31c2a89e07", "name": "Viewer", "description": "Reads the mail on the addresses they hold, and changes nothing.", "permissions": [ "emails:read", "drafts:read", "threads:read", "labels:read", "contacts:read", "calendar:read", "templates:read", "rules:read", "connections:read", "settings:read" ], "builtin": "viewer", "editable": true, "deletable": true, "members": 3, "apiKeys": 1, "createdAt": "2026-08-01T09:00:00.000Z", "updatedAt": "2026-08-01T09:00:00.000Z" } ], "hasMore": false, "nextCursor": null}Gesorteerd op ingebouwde rang en dan op naam (owner, admin, member, viewer, developer, billing, en daarna de rest alfabetisch) in plaats van nieuwste eerst zoals de rest van de API. Een permissiematrix wordt als een ladder gelezen, en sorteren op createdAt zet de breedste rol elke week op een andere regel.
Deze lijst lezen is wat de zes AANLEGT in een workspace die er nog nooit een had. Het aanleggen botst op een unieke index en doet de tweede keer niets, dus de aanroep is idempotent en alleen de eerste schrijft — en daarom kan POST /members altijd een roleId noemen dat bestaat.
Het gebeurt ÉÉN keer. De workspace legt vast dat hij is aangelegd, dus deze leesactie vult een workspace aan die ouder is dan de functie en schrijft daarna nooit meer — en dat is wat het verwijderen van een standaardrol definitief maakt. Een eerdere build voegde bij elke leesactie opnieuw toe welke sjabloonrij ook ontbrak, waardoor een verwijderde Billing bij het volgende paginabezoek terugkwam onder een nieuw id; dat gebeurt niet meer.
members en apiKeys zijn wat verplaatst zou moeten worden voordat de rol weg kan, en dat laat een client waarschuwen vóórdat hij het verwijderen aanbiedt in plaats van na de 409. De rij van de owner leest meestal members: 0: de owner is geen lid van zijn eigen workspace, hij is het account waar die aan hangt.
Er is een hard plafond van 24 eigen rollen, juist zodat dit één antwoord kan zijn. In een workspace met veertig rollen kun je "wie mag versturen als billing@" niet meer met één blik beantwoorden, en dat is de enige vraag waarvoor deze functie bestaat.