Rôles

Every role this workspace defines: the seeded ones first in ladder order (owner, admin, member, viewer, then developer and billing), and everything else alphabetically after them. Not newest-first like the rest of the API, because a permission matrix is read as a ladder and ordering it by createdAt puts the widest role in a different row every week. A renamed seed keeps its rung: the order is read off builtin, not off the name.

A page at a time: follow nextCursor while hasMore is true to read every role. Custom roles are capped on purpose: a workspace with forty of them cannot answer "who can send as billing@" by looking, which is the only question the feature exists to make answerable.

A workspace older than the feature has no role rows at all, and this read SEEDS them rather than reporting an empty list. The seeder writes the six templates and rewrites nothing else, so an edited or renamed role is left exactly as it was, and it is what makes POST /members able to name a roleId that exists. The one row it does rewrite is owner, whose permission list is reset from the current vocabulary on every read, so a workspace seeded two releases ago still holds the permissions added since.

It seeds ONCE. The workspace records that it has been seeded, so this read fills in a workspace older than the feature and then never writes the templates again. That is what a client should know before it draws a confirmation dialog: deleting a seeded role is permanent. A deleted Billing stays deleted and does not come back under a new id on the next read. owner is the exception, restored on every read because it is the row the workspace is keyed on, and it cannot be deleted through this API in any case.

What a KEY may do is its own scopes INTERSECTED with the permissions of the role it was issued under, never the union. A role here that lacks emails:send is a ceiling: a key carrying that scope under that role cannot send, whatever the token says it holds. A key with no role has no ceiling, which is what every key issued before roles existed still has.

Requires the roles:read scope.

Writes a role this workspace invents for itself. builtin comes back null, and only rows like that count against the ceiling. The seeded roles already exist and are not created here; they are not fixtures either, so shaping one of them into what this workspace calls people is often a PATCH rather than a new role.

Implied permissions are expanded as it is written, so a body naming templates:write alone comes back holding templates:read as well. Storing the expanded list is what lets every reader (this API, the console, the key middleware) check one flat array rather than each of them knowing the implication table.

Mind what roles:write is. A key holding it can PATCH the very role that caps it and hand itself the rest of the vocabulary on the next request, because the ceiling is resolved per request rather than frozen into the token. That is the same authority the console gives anybody who can edit roles, and it is not a hole to be plugged here. A role editor that cannot edit its own role is not a role editor. It is a reason not to put roles:write on a key that only ever needed to read the members list.

A permission the calling key or token does not hold is refused with insufficient_authority, a 403, and none of them holds a console-only permission (scope: false on GET /roles/permissions). A role holding addresses:all, billing, workspace:manage or the API-key pair is written in the app.

Requires the roles:write scope.

The vocabulary a role is written in: every permission, the sentence to show a person for it, the heading it belongs under, and whether a key may hold it at all.

Served rather than left to be transcribed, for the same reason the rule vocabularies are derived rather than described: a matrix built from a copied array keeps offering a permission the day one is renamed, and never offers the one added last week.

scope is the field to branch on. Permissions and scopes are one alphabet on purpose (the authority of a key is its own scopes intersected with the permissions of its role, and an intersection is only computable if both sides are drawn from the same list), but they are not the same set. The six console-only entries (addresses:all, the API-key pair, billing, workspace:manage) exist so that a role can say who reaches every address, who may see or move the plan and who may manage the workspace, and no token can ever carry them. The API-key pair is listed too, but API keys stay with the workspace owner whatever a role holds. A key-creation checklist filters on scope; a role matrix does not.

In canonical order, which is the order a stored permissions array comes back in, so a client rendering this list and a client rendering a role show the same permissions in the same sequence.

Behind roles:read, where the console has the same catalogue ungated. The divergence is deliberate: a signed-in person has to be shown the matrix before they can be told which parts of it they may not touch, whereas every request here already carries a key, and a key that may not read roles has no use for the vocabulary of roles.

Requires the roles:read scope.

members and apiKeys are counted at read time rather than stored, so they are the answer now and not the answer when somebody last edited the role. They are what a deletion would have to move.

Requires the roles:read scope.

Rename a role, rewrite its sentence, or replace what it grants.

permissions is REPLACE-WHOLE. There is no way to add or remove a single one and there will not be: the list is what gets audited, and an index-addressed patch is a lost update the first time two tabs are open. "Add domains:write" is a GET and a PATCH in a client that already has the array on screen.

The owner role refuses every edit (changing it would be changing what "owner" means, which is not for a workspace to decide), and it is the only role that refuses one. Everything else takes all three fields, the seeded Admin, Member, Viewer, Developer and Billing included: renaming Billing to "Finance" and rewriting what it grants is an ordinary PATCH. builtin does not move with the name; it goes on recording which template the row was seeded from, which is what keeps the list order stable.

The edit is LIVE. Authority is resolved per request (the scopes on a key intersected with the permissions on this role, every time), so narrowing a role takes effect on the next request anybody holding it makes, with no key rotation needed to make it stick, and widening one takes effect just as immediately, which is the half worth remembering before handing somebody a role to edit.

Adding a permission the calling key or token does not hold is refused with insufficient_authority, a 403, and none of them holds a console-only one such as addresses:all. One the role already holds is kept only if the PATCH sends it back, and a console-only one cannot be added back through this API, so send back every entry you read.

Requires the roles:write scope.

Deletes a role and moves everybody who held it. Only the owner refuses: the roles a workspace was seeded with go the same way as one somebody wrote, because a workspace that never uses Developer or Billing should be able to be rid of them.

Deleting a seeded role is permanent, the same as deleting one somebody wrote. Seeding is a one-time bootstrap recorded against the workspace, not a reconciliation run on every read, so nothing puts a deleted role back.

API keys are re-pointed rather than orphaned, and that is the part worth reading twice: a key whose role had vanished would fall back to NO ceiling, and no ceiling is WIDER than a narrow role, so deleting a restrictive role would quietly promote every key it had been capping. Refusing without reassignTo is what keeps that from being a one-word request.

The two counts come back separately because they are two different things to go and check afterwards. reassigned is people; keysReassigned is programs, which will carry on running under their new ceiling without anybody being told.

A tombstone rather than a 204, matching the rest of the API: the id comes back so a log line can name what went.

Requires the roles:write scope.