---
title: "Rename or re-describe a role"
method: PUT
path: "/api/roles/{role_id}"
tags: ["Permissions"]
---

# Rename or re-describe a role

`PUT /api/roles/{role_id}`

Rename / re-describe a role, deliberately and audited.

Renaming a system TEMPLATE cascades to every company copy of it, in one
statement (owner decision, 2026-08-27). Template and copies are name-identical
by construction — `ensure_company_role_copies` copies `t.name` and nothing
renames a copy — so letting them diverge would make the list HARDER to read,
which is the problem this work exists to fix.

Three guards, in order:

1. **A no-op writes nothing.** The frontend always sends both fields
   (`setRoleForm({name: role.name || '', description: role.description || ''})`),
   so "unset means unchanged" is not available — the diff is computed here
   against the stored row. Without it, opening a template and pressing
   Guardar would rewrite 19 rows across 18 tenants and file 19 audit rows;
   and the `|| ''` would write `''` over every NULL description.
2. **A system row needs `edit_system_role`.** The refusal names the token
   because `useRolesPermissions.js::isPrivilegedGrantRefusal` distinguishes
   retryable refusals by `detail` text, not by status code.
3. **A system COPY may not be renamed at all.** Its name belongs to the
   template. Allowing it manufactures exactly the divergence the cascade
   prevents, and there is no way back — `reset-template` only rewrites
   `modulo.*` rows. The description stays editable.

## Path parameters

- `role_id` integer, required

## Headers

- `x-api-token` string, nullable

## Request body

- RoleUpdate
  - `name` string, nullable
  - `description` string, nullable
  - `edit_system_role` boolean

## Response `200`

Successful Response

- unknown

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/multigest/apis/multigest-protected-api.md) · [All operations](https://skmtc.dev/multigest/apis/multigest-protected-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/multigest/multigest-protected-api/revisions/4b44eb76b3ee/schema)