Roles
Named bundles of permissions, and who holds them.
Create a role
Creates a role in the calling tenant. A role is a named set of permission codes; users hold roles directly or through a group, and their effective permissions are the union of both. Permission codes may be supplied at creation, in which case they are bound in the same operation so the role is never briefly live with none. Requires `role.create`.
List roles
Returns the tenant's roles, paginated. Use this to review what access exists before granting more. Requires `role.read`.
Clone a role
Copies an existing role's permission set into a new role under a new name. Use this to derive a narrower variant of a working role rather than reassembling its permissions by hand. Requires `role.create`.
List the users holding a role
Returns the users who hold this role, whether directly or through a group. Read this before changing or deleting a role — it is the list of people the change will affect. Requires `role.read`.
Get a role
Returns one role and the permission codes it carries. Requires `role.read`.
Update a role
Changes a role's name or description. Permission membership is managed through the role's permissions collection rather than here. Requires `role.update`.
Delete a role
Soft-deletes a role. The role stops granting access immediately and can be restored. A role still assigned to a user or group cannot be deleted — revoke the assignments first. Requires `role.delete`.
Restore a deleted role
Reinstates a soft-deleted role together with the permissions it carried. Requires `role.restore`.
Grant a permission to a role
Binds a permission code to the role. Everyone holding the role gains it on their next request — permissions are resolved per request, not carried in the caller's token. Requires `role.permission.assign`.
List a role's permissions
Returns the permission codes bound to this role. Requires `role.permission.read`.
Revoke a permission from a role
Removes one permission from a role. Everyone holding the role loses that access on their next request. Requires `role.permission.revoke`.
Copy permissions between roles
Copies every permission from one role onto another, for building a variant of an existing role without re-selecting each permission. Requires `role.permission.assign`.