# Update Role

Rename a custom role or replace its permissions. Members who hold the role get the new permissions. Global roles can't be changed.

`PUT https://connect.mindcloud.co/v2/roles/:roleId`

Permissions: `role:manage`.

## Parameters

### Path

- `roleId` (string, required): The role's id, from List Roles.

### Headers

- `X-Company-Id` (string): Optional. The id of the organization to act in. Leave it out to act in the API key's own organization. A key can also act in its child organizations, and, with "Use this key across all of your organizations" on, in every organization its creator can open in the app. List them with GET /v2/companies. Every response's X-Company-Id header names the organization it acted in. See [Organizations](https://mindcloud.co/docs/api/rest/introduction/organizations).

### Body

- `name` (string): A new name, up to 255 characters.
- `description` (string): A new description, up to 255 characters.
- `permissions` (array): The full new set of permission keys. Replaces the current set.

## Example request

```bash
curl --request PUT \
  --url 'https://connect.mindcloud.co/v2/roles/Rl5wB9cF3hJp' \
  --header 'Authorization: Bearer $MINDCLOUD_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Support (read-only)",
  "description": "Read-only access for the support team",
  "permissions": [
    "workflow:read"
  ]
}'
```

## Response fields

- `id` (string): Unique id of the role.
- `name` (string): The role's name.
- `description` (string): The role's description. Empty when nobody wrote one.
- `isAdmin` (boolean): True if the role grants admin rights.
- `isGlobal` (boolean): True for roles MindCloud provides to every company. Global roles are read-only: writing one answers 404.
- `createdOn` (date): When the role was created.
- `memberCount` (number): How many people in the company hold the role, people whose invite is pending included. A role with members cannot be deleted.
- `permissions` (array of objects): Everything the role allows, as { key, name } pairs.
  - `key` (string): The permission key, such as workflow:run.
  - `name` (string): The permission's display name.

## Errors

- 400 Bad request (INVALID_QUERY, NO_FIELDS_TO_UPDATE, ROLE_PERMISSIONS_UNKNOWN_KEYS): `VALIDATION_FAILED` / `NO_FIELDS_TO_UPDATE` "Provide at least one of "name", "description" or "permissions"."
- 403 Access denied (API_KEY_PERMISSION_DENIED, MEMBER_ACTOR_NOT_RESOLVED, ROLE_PERMISSIONS_ADMIN_FORBIDDEN, ROLE_PERMISSIONS_EXCEED_ACTOR): `FORBIDDEN` / `ROLE_PERMISSIONS_ADMIN_FORBIDDEN` "Company roles cannot grant admin-only permissions."
- 404 Role not found: `NOT_FOUND` / `ROLE_UPDATE_NOT_FOUND` "Role not found for this company."
- 409 Duplicate role name: `CONFLICT` / `ROLE_UPDATE_DUPLICATE_NAME` "A role with this name already exists in the company."
- 500 Write failed (ROLE_UPDATE_QUERY_FAILED, ROLE_RELOAD_FAILED): `INTERNAL_ERROR` / `ROLE_UPDATE_QUERY_FAILED` "Failed to update role."