Update Role
PUT /roles/{role_id}
Redefine a role. THIS CHANGES WHAT EVERY HOLDER MAY DO, IMMEDIATELY.
permissions REPLACES the list rather than merging into it, so a value
left out is a permission taken away from everyone who holds the role. That
is why this operation is tiered destructive rather than write: it is a
privilege change, and “re-define what the sales team may do” must not ride
along in the same grant as “rename a team”.
The app refuses to edit the permissions of its locked system roles
(admin, service_provider) - stripping roles:manage from admin
would lock the organisation out with no recovery path - and refuses to
grant anything the caller does not hold. Both reach you as a 403.
Authorizations
Parameters
Path Parameters
Role id (UUID).
Role id (UUID).
Header Parameters
Request Body required
Replace a role’s definition. Mirrors roles.RoleUpdateRequest.
permissions is a REPLACEMENT, not a merge, and it takes effect for
everyone who already holds the role. That is why the operation is tiered
destructive rather than write.
object
Per-role reveal/ownership limits. Mirrors roles.RepLimitsSettings.
The three Literals are closed here rather than left as strings because
they reach the app’s own Literal inside _apply_rep_limits.
Responses
200
Successful Response
object
An open envelope for a single role, team, member or account record.
Open on purpose. The app’s own response models on this surface grow with
the product - RoleResponse gained rep_limits and manages_role_slugs,
TeamResponse gained channel counts and a campaign count - and a pinned
mirror would SILENTLY DROP whatever it had not caught up on. A dropped
permission in a role read is the worst possible kind of stale: it reads as
“they do not have it”.
object
object
Whether there are more pages
Items per page
Current page number (1-indexed)
Total number of items
422
Validation Error