---
title: "Update an existing role's fields"
method: PATCH
path: "/roles/{roleId}"
tags: ["Role"]
---

# Update an existing role's fields

`PATCH /roles/{roleId}`

Updates the role identified by `roleId` under the tenant specified by the required `tenant-id` header. Use this to change a role's name or description after creation; to create a new role use `POST /roles`. This is a full replacement, not a partial merge: any field omitted from the request body (`name` or `description`) is cleared on the role rather than left unchanged, so callers must resend the current value for any field they do not intend to change. Returns 200 with the full updated role object (`RoleResponseDto`). Returns 400 if the `tenant-id` header is absent or blank. Note: if the role does not exist, the current implementation returns 500 rather than 404 (tracked in CP-36405).

## Path parameters

- `roleId` string, required

## Headers

- `tenant-id` string

## Request body

- RoleUpdateRequest — Request body for updating a role. This is a full replacement, not a partial merge: any field omitted (`name` or `description`) is cleared on the role rather than left unchanged.
  - `name` string, required — Role name
  - `description` string — Role description

## Response `200`

Role updated successfully

- RoleResponseDto — Role information response
  - `id` string — Role ID
  - `name` string — Role name
  - `tenantId` string — Tenant ID
  - `description` string — Role description
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `createdBy` string — ID of the user who created the role
  - `updatedBy` string — ID of the user who last updated the role

## Other responses

- `400` — Bad request - Invalid request parameters or missing required headers
- `401` — Authentication required - Valid authentication token is missing or invalid
- `403` — Forbidden - User does not have the required permissions to update roles
- `500` — Internal server error - An unexpected error occurred while processing the request. No response body is returned. Note: a non-existent role ID currently also surfaces here as a 500 rather than a 404, since not-found conditions are not distinguished from other failures (tracked in CP-36405).

---

[API](https://skmtc.net/certifyos/apis/certify-api-layer.md) · [All operations](https://skmtc.net/certifyos/apis/certify-api-layer/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/certifyos/certify-api-layer/revisions/563848e0ecc0/schema)