Change a role

update_workspace_role

Changes the name or the permissions of a custom role, for everyone who holds it at once.

POST /v1/update_workspace_roleScopeworkspaces:writeMakes changes

The name and the permission list are both required on every call, even when one of them is not changing, so send the current value of the one you are not changing. The permission list replaces the old one rather than adding to it, so send the full set.

Everyone on that role is affected at once, so read get_role_member_counts first to see how many people that is. workspace.delete and billing.manage stay with the owner and are not accepted, and an empty permission list is refused.

It needs the Manage roles permission (roles.manage) and the workspace on Pro or Enterprise, otherwise it is refused with You must upgrade to the Pro plan to manage roles! See Members and roles.

Request

Call it with a POST to https://api.modulify.ai/v1/update_workspace_role, sending the inputs below as a JSON object. The token needs the workspaces:write scope.

It makes changes, so send an Idempotency-Key header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

curl -X POST https://api.modulify.ai/v1/update_workspace_role \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"WORKSPACE_ID","roleId":"ROLE_ID","name":"NAME","permissions":[]}'

Over MCP, the same method is the update_workspace_role tool.

Inputs

Input	Type	Required	Description
`workspaceId`	string	Yes	The workspace id.
`roleId`	string	Yes	The role id.
`name`	string	Yes	The role name, 2 to 32 characters. Required on every call even when it is not changing.
`permissions`	array of strings	Yes	The full new permission set, which replaces the old one rather than adding to it, with at least one of `workspace.access`, `workspace.update`, `members.manage`, `roles.manage`, `projects.delete`, `projects.transfer`, `projects.move`, `projects.domains`, `folders.edit`, `folders.delete`, `folders.move` and `api.access`. Required on every call even when it is not changing.

Response

Every call answers with the JSON envelope of success, message, data, code and version. data holds the result described above, and on a method that returns a total, count carries it. The response headers carry the call's X-Request-Id and what is left of your per-minute budget in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Errors explains every status code a call can answer with.