---
title: "corestack_team_role_update"
url: https://docs.corefinity.com/mcp/tools/corestack_team_role_update
type: tool
last_updated: 2026-11-13
feature: team
related:
  - https://docs.corefinity.com/api/reference/organisation/update-custom-role.md
  - https://docs.corefinity.com/guides/organisation/people/users-and-invitations.md
---
# corestack_team_role_update

**Edit a custom role.** Rename one of your company's custom roles and set the permissions it gives (permissions you hold yourself). Scope: write.

- Scope: `write`
- Runs as a task: no

## When to use it

Rename one of your company's custom roles and set the permissions it gives (the whole set; permissions the person you act
for holds). Everybody holding the role gets the new set. This is `POST /api/roles/{id}/update`. A standard role, or
another company's, answers `tenant_mismatch`.

## Inputs

- `role_id` (integer, ≥ 1, required): the custom role's id from corestack_team_roles_list.
- `name` (string, up to 255 characters, required)
- `permissions` (array of strings, at least one, required): permission slugs.
- `scope` (integer, optional): always 4 (Custom); leave it out or send 4. It cannot be changed.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "name": {
      "maxLength": 255,
      "type": "string"
    },
    "permissions": {
      "description": "The whole set of permission slugs the role gives from now on.",
      "items": {
        "maxLength": 255,
        "type": "string"
      },
      "minItems": 1,
      "type": "array"
    },
    "role_id": {
      "description": "The custom role's id (corestack_team_roles_list).",
      "minimum": 1,
      "type": "integer"
    },
    "scope": {
      "description": "Optional. A custom role's scope is always 4 (Custom) and cannot be changed: leave it out, or send 4. Any other value is refused.",
      "type": "integer"
    }
  },
  "required": [
    "role_id",
    "name",
    "permissions"
  ],
  "type": "object"
}
```

## Refusals

- `forbidden`: you may not edit roles (an owner, or the Edit Roles permission, may).
- `invalid_arguments`: on `permissions`: "… is not a permission." for a name that is not one ("… is not a permission (it was removed)." for a retired one, such as `assignRoles`), or "You are not allowed to add … permission." for one you do not hold, or "… is a Corefinity staff permission: a company's custom role cannot hold it." for a staff permission, even one you hold; or on `name`.
- `invalid_arguments`: on `scope`: "A custom role's scope is always Custom and cannot be changed." for any integer other than 4. A non-integer gets the normal schema type error.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_team_role_update",
  "arguments": {
    "role_id": 77,
    "name": "Release managers",
    "permissions": ["viewWebsites"]
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_team_role_update with role_id 77, name Release managers, permissions ["viewWebsites"]. (Edit a custom role.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [POST /api/roles/{id}/update](https://docs.corefinity.com/api/reference/organisation/update-custom-role.md)
- Guide: [Users and invitations](https://docs.corefinity.com/guides/organisation/people/users-and-invitations.md)
