Update a custom role

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

patch/api/v3/roles/{role_id}

Request

Base URL
https://embedded.improvado.io
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.

role_idinteger required

titlestring required

Role title. Must be non-empty and unique within the agency.

descriptionstring

Optional description.

layersobject required

Permissions grouped by product layer. Use codes from GET /api/v3/roles/permissions.

Updated role

idinteger required

Role ID

titlestring required

Role title (unique within the agency)

descriptionstring required

Optional human-readable description

is_systemboolean required

True for built-in Improvado-managed roles. Read-only — cannot be edited or deleted.

is_internalboolean required

True for internal-only roles (impersonation, guest viewers). These are never listed in the API.

layersobject required

Permissions grouped by product layer. Layer codes match code in the permissions catalog.

user_countinteger required

Number of users currently assigned to this role across the agency.

No recorded changes to this operation across all 1 revision of this API.