Skip to main content
A role is a named set of permissions. Users carry a role through their organization membership. Search columns: name, description Standard CRUD applies. See standard endpoints.
Requires admin access, or the Role.Read and Role.Update permissions.

​
Fields

Every property the API returns for a role.

​
Two permission fields

permissionsV2 is the form BuildingSwell writes today: a list of statements, each naming a subject, the actions it allows, and optional row and field limits. permissions is the older flat list of strings, kept so existing integrations keep working. Read both, and write permissionsV2.

​
Statement shape

​
Duplicate a role

Copying an existing role is usually faster than assembling permissions from scratch:
You get back a new role with the same permissions under a unique name.
isApiKey marks the synthetic role behind an API key. Leave it alone on roles you create.

​
What you can write

Everything else in the table above is set by BuildingSwell.

​
Deleting

DELETE /role/{id} is destructive.Permanently removes the role. This cannot be undone and there is no archive for roles.Users assigned to the role keep pointing at an id that no longer resolves, which leaves them without permissions. Move them to another role first with PATCH /organization-member/{id}.
See archiving and deleting for the full picture across resources.