Manage custom workspace roles and inspect the available permission catalog.
Each agency ships with a fixed set of system roles (Workspace Admin, Editor, Viewer, Data Manager, Data Load Manager, Data Analyst). On top of these you can define custom roles scoped to the agency and assign them to users in any workspace.
Capabilities:
- List system + custom roles (each role carries its assigned
user_count). - Fetch the curated permission catalog: a stable, ordered list of product layers with
permissions, including human-readable
titleanddescriptionfor each entry. - Create, rename, edit, and delete custom roles. System roles are read-only.
- List users currently assigned to a role for impact preview.
Delete semantics: deleting a custom role atomically reassigns every user holding it to the
system Viewer role; the response returns reassigned_users_count.
All Roles endpoints require an agency-chief Basic Auth credential and the can_use_embedded_api
flag enabled for the agency.
List roles
Returns every role visible to the agency: non-internal system roles
(Workspace Admin, Editor, Viewer, etc.) plus all agency-scoped custom roles.
Each entry carries user_count — the number of users currently assigned to that role.
List roles › Responses
List of roles
Create a custom role
Creates a new agency-scoped custom role. The role's title must be unique within the agency
and every (layer, permission) pair must come from the catalog (GET /api/v3/roles/permissions).
Create a custom role › Request Body
titleRole title. Must be non-empty and unique within the agency.
Permissions grouped by product layer. Use codes from GET /api/v3/roles/permissions.
descriptionOptional description.
Create a custom role › Responses
Role created
idID of the newly created role.
Permissions catalog
Curated catalog of product layers and the permissions that can be granted on each.
Stable display order; title/description are human-readable and safe to render directly.
Permissions catalog › Responses
Catalog of layers and permissions.
Ordered list of product layers with their valid permissions.
Get a role
Returns one role. Visible to the agency only if it's a non-internal system role or an agency-scoped custom role belonging to the calling agency.
path Parameters
role_idRole ID
Get a role › Responses
Role detail
idRole ID
titleRole title (unique within the agency)
descriptionOptional human-readable description
is_systemTrue for built-in Improvado-managed roles. Read-only — cannot be edited or deleted.
is_internalTrue for internal-only roles (impersonation, guest viewers). These are never listed in the API.
Permissions grouped by product layer. Layer codes match code in the permissions catalog.
user_countNumber of users currently assigned to this role across the agency.
Delete a custom role
Delete an agency-scoped custom role. Users currently assigned to it are atomically reassigned to the system Viewer role; the response returns how many were moved. System roles cannot be deleted.
path Parameters
role_idDelete a custom role › Responses
Role deleted; affected users reassigned to Viewer.
reassigned_users_countNumber of users that were reassigned to the Viewer system role as part of the delete.
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.
path Parameters
role_idUpdate a custom role › Request Body
titleRole title. Must be non-empty and unique within the agency.
Permissions grouped by product layer. Use codes from GET /api/v3/roles/permissions.
descriptionOptional description.
Update a custom role › Responses
Updated role
idRole ID
titleRole title (unique within the agency)
descriptionOptional human-readable description
is_systemTrue for built-in Improvado-managed roles. Read-only — cannot be edited or deleted.
is_internalTrue for internal-only roles (impersonation, guest viewers). These are never listed in the API.
Permissions grouped by product layer. Layer codes match code in the permissions catalog.
user_countNumber of users currently assigned to this role across the agency.
List users assigned to a role
Returns the users currently holding the role, with their workspace assignment. Useful for impact preview before editing or deleting the role.
path Parameters
role_idList users assigned to a role › Responses
Users assigned to the role.