RoleService

Manages roles and their associated permissions within an organization. System roles (Admin, Manager, Member, Super Admin) are immutable.

Methods

Method	Description
ListRoles	List all roles for the organization
CreateRole	Create a custom role
UpdateRole	Update a custom role
DeleteRole	Delete a custom role

ListRoles

List all roles for the organization, including system roles.

Authorization: Requires VIEW_ROLES permission

Request: ListRolesRequest

Empty request.

Response: ListRolesResponse

Field	Type	Description
roles	Role[]	List of roles.

CreateRole

Create a custom role with a set of permissions.

Authorization: Requires MANAGE_ROLES permission

Request: CreateRoleRequest

Field	Type	Description
name	string	Role name. Max 200 characters.
permissions	Permission[]	Permissions to grant.

Response: CreateRoleResponse

Field	Type	Description
role	Role	The created role.

Example

TypeScript (Connect-Web)

const response = await roleClient.createRole({
  name: "Campaign Manager",
  permissions: [
    Permission.VIEW_CAMPAIGNS,
    Permission.MANAGE_CAMPAIGNS,
    Permission.VIEW_MEMBERS,
  ],
});

Go (gRPC)

resp, err := roleClient.CreateRole(ctx, &pidgrv1.CreateRoleRequest{
    Name: "Campaign Manager",
    Permissions: []pidgrv1.Permission{
        pidgrv1.Permission_VIEW_CAMPAIGNS,
        pidgrv1.Permission_MANAGE_CAMPAIGNS,
        pidgrv1.Permission_VIEW_MEMBERS,
    },
})

UpdateRole

Update a custom role’s name or permissions. System roles cannot be updated.

Authorization: Requires MANAGE_ROLES permission

Request: UpdateRoleRequest

Field	Type	Description
id	string	Role ID.
name	string	Updated name.
permissions	Permission[]	Updated permissions.

Response: UpdateRoleResponse

Field	Type	Description
role	Role	The updated role.

DeleteRole

Delete a custom role. System roles and roles with assigned users cannot be deleted.

Authorization: Requires MANAGE_ROLES permission

Request: DeleteRoleRequest

Field	Type	Description
id	string	Role ID to delete.

Response: DeleteRoleResponse

Empty response on success.

Role Message

Field	Type	Description
id	string	Unique identifier.
slug	string	URL-safe slug (e.g., admin, manager).
name	string	Display name.
is_default	bool	Whether this is a system-seeded role.
is_system	bool	Whether this role is immutable (e.g., super_admin).
permissions	Permission[]	Granted permissions.