---
title: "Patch Role API"
method: PATCH
path: "/authz2/v1/roles/{role_id}"
tags: ["esper_cloud_api_Roles"]
---

# Patch Role API

`PATCH /authz2/v1/roles/{role_id}`

Updates the name and/or description of an existing custom RBAC role.

Use this endpoint to correct a role's display name or description without affecting the scopes or user assignments associated with that role.

**About Patch Role**

This endpoint modifies the metadata of an existing custom role — its name and description — and leaves the role's assigned scopes and user assignments unchanged. It accepts the same Role schema as POST /authz2/v1/roles/. To modify the permissions a role grants, use PUT /authz2/v1/roles/{role_id}/scopes instead.

**Key Fields / Request Body**

name — the updated display name for the role

description — the updated description for the role

**Common Use Cases**

Renaming a role after a team restructure or job function change

Correcting a typo or clarifying a role description to make the role list more auditable

**Best Practices**

Notify any Enterprise Admins or automation that reference this role by name that it has been renamed — role_id is stable across renames but human-readable references in scripts or documentation are not

Use GET /authz2/v1/roles/{role_id} to confirm the current name and description before updating

**Workflow**

Call GET /authz2/v1/roles/{role_id} to confirm the current role metadata

PATCH to this endpoint with the updated name and/or description

Confirm the changes in the returned RoleResponse

## Path parameters

- `role_id` string, uuid, required

## Request body

- EsperCloudApiRole
  - `name` string
  - `description` string

## Response `200`

Request Succeded

- EsperCloudApiRoleResponse
  - `id` string
  - `name` string
  - `description` string
  - `role_type` integer

## Other responses

- `400` — Bad request
- `401` — Unauthorized request

---

[API](https://skmtc.net/esper/apis/esper-api-reference.md) · [All operations](https://skmtc.net/esper/apis/esper-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/esper/esper-api-reference/versions/e1f64cbb488e/schema)