# update_workspace_role

Source: https://modulify.ai/docs/api/workspaces/update-workspace-role

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

- Title: Change a role
- Scope: `workspaces:write`
- Access: Makes changes
- Endpoint: `POST /v1/update_workspace_role`

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](https://modulify.ai/docs/reference/members-and-roles#create-a-custom-role).

## 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](https://modulify.ai/docs/api/idempotency) header whenever you might retry it. A retry with the same key gets the first answer back instead of running again.

```bash
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](https://modulify.ai/docs/mcp/workspaces/update-workspace-role).

## 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](https://modulify.ai/docs/api/requests-and-responses#the-response) 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](https://modulify.ai/docs/api/requests-and-responses#headers-on-every-method-call) 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](https://modulify.ai/docs/api/errors) explains every status code a call can answer with.