---
title: "PUT /v1/iam/roles/{id}"
method: PUT
path: "/v1/iam/roles/{id}"
tags: ["IAMService"]
---

# PUT /v1/iam/roles/{id}

`PUT /v1/iam/roles/{id}`

UpdateRole 更新角色，采用 PATCH 语义：仅 optional 字段存在时更新。
 内置角色禁止修改 status；setPermissions/setMenus 为 true 时整体覆盖对应授权集合。

## Path parameters

- `id` string, required

## Request body

- IamV1UpdateRoleRequest — UpdateRoleRequest 使用 PATCH 语义，未传的 optional 字段保持不变。
  - `dataScope` integer — 数据范围：1=全部数据，2=部门数据，3=仅本人，4=自定义。
  - `description` string
  - `id` string
  - `menuIds` string[]
  - `name` string
  - `permissionIds` string[]
  - `setMenus` boolean — 为 true 时用 menuIds 整体替换角色菜单；为 false 时忽略 menuIds。
  - `setPermissions` boolean — 为 true 时用 permissionIds 整体替换角色权限；为 false 时忽略 permissionIds。
  - `sortOrder` integer
  - `status` integer — 状态：1=启用，2=禁用。

## Response `200`

OK

- IamV1UpdateRoleReply
  - `role` IamV1Role
    - `createdAt` string, date-time
    - `createdBy` string — 创建人 user_id；为 0 表示系统/迁移创建（历史数据）。
    - `createdByName` string — 创建人展示名（昵称优先，回退用户名）；空表示系统创建或用户已不存在。
    - `dataScope` integer — 数据范围：1=全部数据，2=部门数据，3=仅本人，4=自定义。
    - `description` string
    - `id` string
    - `isBuiltin` boolean — 内置角色。内置角色禁止删除，且禁止修改 status。
    - `name` string
    - `sortOrder` integer
    - `status` integer — 状态：1=启用，2=禁用。
    - `updatedAt` string, date-time
    - `updatedBy` string — 最后修改人 user_id；为 0 表示未修改过或系统修改。
    - `updatedByName` string — 最后修改人展示名；空表示未修改过、系统修改或用户已不存在。

---

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