Skip to content

Patch Role API
Stable

Request

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

Security
esper_cloud_api_apiKey
Path
role_idstring, (uuid)required

Role ID

Bodyapplication/jsonrequired
namestring
descriptionstring
cURL
curl -i -X PATCH \
  'https://api.esper.io/_mock/openapi/authz2/v1/roles/{role_id}' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "string",
    "description": "string"
  }'

Responses

Request Succeded

Bodyapplication/json
idstring
namestring
descriptionstring
role_typeinteger
Response
{
  "id": "string",
  "name": "string",
  "description": "string",
  "role_type": 0
}