---
title: "Update a custom role"
method: PATCH
path: "/api/v3/roles/{role_id}"
tags: ["Roles"]
---

# Update a custom role

`PATCH /api/v3/roles/{role_id}`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/roles/{role_id}`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/roles/:role_id/patch.ts> (a function with typed inputs; its response is checked against the schema)

Update an agency-scoped custom role's title, description, and permission set.
System roles are read-only and cannot be modified.

## Path parameters

- `role_id` integer, required

## Request body

- RoleWriteRequest: Payload for creating or updating a custom role.
  - `title` string, required: Role title. Must be non-empty and unique within the agency.
  - `description` string: Optional description.
  - `layers` object, required: Permissions grouped by product layer. Use codes from `GET /api/v3/roles/permissions`.

## Response `200`

Updated role

- Role: Workspace role (system or agency-custom).
  - `id` integer, required: Role ID
  - `title` string, required: Role title (unique within the agency)
  - `description` string, required: Optional human-readable description
  - `is_system` boolean, required: True for built-in Improvado-managed roles. Read-only — cannot be edited or deleted.
  - `is_internal` boolean, required: True for internal-only roles (impersonation, guest viewers). These are never listed in the API.
  - `layers` object, required: Permissions grouped by product layer. Layer codes match `code` in the permissions catalog.
  - `user_count` integer, required: Number of users currently assigned to this role across the agency.

## Other responses

- `400`: Invalid payload.
- `403`: System roles cannot be modified.
- `404`: Role not found.
- `409`: Another role in this agency already uses this title.

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)