---
title: "Update a role"
method: PUT
path: "/api/v1/roles/{roleid}"
tags: ["Roles"]
---

# Update a role

`PUT /api/v1/roles/{roleid}`

## Request

- Base URL: `https://docs.anzworldline-solutions.com.au`
- URL: `https://docs.anzworldline-solutions.com.au/api/v1/roles/{roleid}`
- Auth: none declared
- TypeScript: <https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/docs/api/v1/roles/:roleid/put.ts> (a function with typed inputs; its response is checked against the schema)

Updates an existing role's name, key, description, can-grant flags and parent. PUT is a full replace: every field of the role is overwritten from the request body, so clients must send the complete role representation — omitted fields are reset (booleans default to false, omitted roleKey/description are cleared, omitted parentRoleId reparents to root). A null parentRoleId turns the role into a root role. Reparenting under the role's own descendant is rejected. System and locked roles cannot be updated. Note: the role is updated in place — grants and permissions attached to the role are preserved.

## Path parameters

- `roleid` string, required

## Request body

- RoleForm
  - `roleName` string, required
  - `roleKey` string
  - `parentRoleId` string
  - `canEditUsers` boolean
  - `canEditPermissions` boolean
  - `canEditLayouts` boolean
  - `description` string

## Response `200`

Role updated successfully

- ResponseEntityRoleDetailView
  - `errors` ErrorEntity[]
    - `errorCode` string
    - `message` string
    - `fieldName` string
  - `entity` RoleView
    - `id` string
    - `name` string
    - `description` string
    - `roleKey` string
    - `parent` string
    - `editPermissions` boolean
    - `editUsers` boolean
    - `editLayouts` boolean
    - `locked` boolean
    - `system` boolean
    - `roleChildren` RoleView[]
    - `childCount` integer, required: Number of direct child roles, independent of children hydration
    - `userCount` integer, required: Number of users directly granted this role, matching the totals of the role users listing: inherited grants and hidden users (system, anonymous, default, flagged for deletion) are not included
    - `dbfqn` string
    - `fqn` string
  - `messages` MessageEntity[]
    - `message` string
  - `i18nMessagesMap` object
  - `permissions` string[]
  - `pagination` Pagination
    - `currentPage` integer
    - `perPage` integer
    - `totalEntries` integer

## Other responses

- `400`: Bad request - invalid role name, or the reparent would create a hierarchy cycle
- `401`: Unauthorized - authentication required
- `403`: Forbidden - admin permissions required, or the role is a system or locked role
- `404`: Role or parent role not found
- `409`: Conflict - duplicate role key, or duplicate role name under the same parent

## Changes

- **2026-10-30** `4fd8e917d458`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/changes/api/v1/roles/:roleid/put.md)

---

[API](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api.md) - [All operations](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/anzworldline-solutions/apis/dotcms-rest-api/revisions/4fd8e917d458?raw)