openemail roles

Resolves one page of the roles the workspace defines. The seeded roles come first in ladder order (Owner, Admin, Member, Viewer, Developer, Billing) and custom roles follow alphabetically. The order is read from builtin, so a renamed seeded role keeps its place.

A workspace older than roles has no role rows, and the first read seeds them instead of returning an empty list. Seeding runs once per workspace, and afterwards only the owner role is ever restored, so a seeded role you delete stays deleted. Each row carries members and apiKeys counts computed at read time.

A role is a ceiling for the keys issued under it. What a key may do is its own scopes intersected with its role's permissions, resolved on every request, so a key holding emails:send under a role without it cannot send. A key with no role has no ceiling.

Add --all to walk every page: a table on a terminal, one JSON object per line when piped or with --ndjson, and one { items, hasMore, nextCursor } document with --json. --max <n> stops after that many items.

Resolves a single role by id. There is no lookup by name, because every role's name except the owner's can be edited.

members and apiKeys are counted when you call rather than stored, so they describe what a deletion would have to move right now. permissions is the stored list with implied permissions already expanded, in canonical order, so it can be longer than what was sent when the role was written.

Writes a role the workspace defines for itself. builtin comes back null and both usage counts are zero. Only roles like this count toward the ceiling of 24 custom roles, past which the call is 422 role_limit_reached.

Implied permissions are expanded as the role is stored, so templates:write alone comes back holding templates:read too, and roles:write brings roles:read and members:read. Read the final list off the result rather than the request. A string that is not in the vocabulary is refused with 422 invalid_parameter rather than dropped.

Be careful with roles:write. Authority is resolved per request, so a key holding it can edit the very role that caps it and widen itself on the next call. Keep it off keys that only need to read.

Patches the name, description or permission list of a role. Every seeded role except Owner takes all three, so renaming Billing to Finance and rewriting what it grants is an ordinary update. The owner role refuses any edit with 409 role_immutable.

permissions replaces the whole list and is expanded with implied permissions on the way in. There is no way to add or remove one entry, so read the role, change the array and send all of it. Leave a field out to keep it, and send description: null to clear the note.

The change is live. Authority is resolved on every request, so narrowing a role takes effect for its members and keys on their next call without rotating anything, and widening it takes effect just as fast.

Deletes a role. Every role except Owner can go, seeded ones included, and deleting a seeded role is permanent because seeding never runs twice. The owner role is refused with 409 role_undeletable.

While any member, API key or unanswered invitation still points at the role, the call needs --reassign-to and is refused with 409 role_in_use without it. The server will not guess, because a key whose role vanished would fall back to no ceiling at all, which is wider than the role being removed. Members, keys and pending invitations move to the named role in one transaction. A role nobody holds deletes without it.

The tombstone reports reassigned people and keysReassigned keys separately. Log the second: those programs keep running under a new ceiling and nobody is told.

Resolves every permission as a plain array, in the canonical order a stored role's permissions also uses. Each entry carries the label to show beside a checkbox and the group heading it belongs under, so a permission matrix can be rendered from this rather than from a list copied into your code.

scope is the field to branch on. Permissions and API key scopes share one alphabet, which is what lets a role cap a key, but they are not the same set. Six are console-only. addresses:all lets a role reach every address on every domain of the workspace, including ones added later, with no grant, billing:read and billing:write say who may see or change the plan, and workspace:manage who may manage the workspace. api-keys:read and api-keys:write are listed too, but API keys stay with the workspace owner whatever a role holds. No key or access token can ever hold any of the six, so they come back with scope: false. Filter on scope for a key scope picker and ignore it for a role editor.