Roles & Access and governance (RBAC)

Open in

View as Markdown

Open in ChatGPT Open in Claude

Conversa Labs

Last updated on Sep 7, 2026

Overview

The native Roles & Access module controls what each person can open, read, and change in an account. In addition to the default Administrator and Agent profiles, an Administrator can create roles with granular permissions, operational team/inbox scope, and personal-data visibility rules.

This module belongs to the ConversaLabs installation and does not depend on a legacy enterprise edition's premium Custom Roles feature. When a native role is assigned to an Agent, it becomes authoritative: a missing permission is a denial even when the generic Agent profile would normally access that surface.

Prerequisites

The Administrator profile to create, edit, delete, or assign roles.
Granular permissions, Field-level permissions, and Platform governance enabled on the account to use permissions/scope, field rules, and the template gallery respectively.
A native role can only be assigned to an Agent in the same account. Administrators retain full access and cannot receive a native role.

Step by step

Open Settings → Roles & Access.
Select New role or Create from template.
Enter a name and description, then select only the required permissions.
Under Scope, choose Entire account, Specific teams, or Specific inboxes. A scoped role must contain at least one team/inbox from its own account.
Under Fields, set Contact and Organization data to Visible, Masked, or Hidden.
Save. In Settings → Agents, edit an Agent and assign the role.
Validate with a test account using that role: navigation, direct URLs, reads, creates, updates, deletes, exports, and real-time events must all follow the role.

How the three layers work

Permissions (L1): each area has its own read or management key. Sensitive operations have separate keys, including contact export/deletion, report export, audit, governance, data-subject requests, and administrative contract actions. Navigation hides unavailable actions, while the backend always makes the final authorization decision.
Operational scope (L2): for conversations and people, Specific teams and Specific inboxes constrain lists, search, counters, direct-ID access, bulk actions, exports, and real-time delivery. Resources linked to a conversation, contact, team, or inbox follow the available relationship. Global records/settings with no such relationship remain controlled by L1; scope does not invent a relationship that does not exist.
Field visibility (L3): Contact rules cover name, email, phone, identifier, tax ID, address, and custom/additional attributes. Organization rules cover tax ID, email, phone, and address. Rules are applied to API responses, CSV exports, and real-time events. Masked or hidden fields are also blocked from editing so a client cannot replace the real value with a mask.

Important rules

An assignment can never reference a role from another account.
Assigning a native role clears any Enterprise custom role on the same membership; the two authorization models are never silently combined.
An assigned role cannot be deleted. Remove or replace all assignments first.
Disabling Granular permissions disables native-role effects and restores the account's standard Administrator/Agent behavior.
Administrator always remains outside native-role restrictions. Use an Agent to test least privilege.

Custom Roles (legacy Enterprise) is now a hard gate

The premium Custom Roles feature — the old Enterprise implementation, distinct from the native module described above — is now blocked end to end by the custom_roles feature, which ships turned off on every account. What changes in practice:

The Custom Roles API is refused without the feature. It answers 401 with "You are not authorized to do this action". The check runs before the profile check, so not even an Administrator can list, open, create, edit, or delete a custom role while the feature is off.
Assigning a custom role to an agent is silently ignored. If the feature is off and the request carries a custom role, the assignment is simply not written — with no error. Clearing the assignment (sending an empty value) still works on purpose, so an account that lost the feature can still remove a stale assignment left behind.
Nobody who already used it loses anything. On upgrade, a data routine turns the feature on automatically for every account that already has custom roles created. It only turns it on where use is demonstrated, re-reads the state before writing (running it twice changes nothing), and turns nothing off on the way back — a feature enabled by hand by an operator is indistinguishable from one it enabled.
A new account still starts without the feature, which is the default behavior.

The native Roles & Access module does not depend on this feature. It is governed by Granular permissions, which ships enabled. If your account only uses native roles, none of this changes for you.

Settings & options

Role templates: start from a governance-gallery template when it matches the person's responsibility, then review every permission before saving; a template never replaces a least-privilege review.
Scope: prefer specific teams or inboxes when the work does not need the whole account. Review scope whenever an Agent changes team or responsibility.
Fields: use Masked to support service without revealing a value and Hidden when the person must not read it at all. Record the personal-data rule's rationale in your privacy policy.

Use cases

An outsourced support team limited to one inbox with phone/email masked.
A DPO who handles data-subject requests and audit without operational administration.
A supervisor with team conversations, reports, and team management but no integrations or billing.
Finance staff with payments and exportable reports but no access to unrelated messages.

Tips, limits & best practices

Grant the smallest permission combination that lets the work be completed, and validate the role with a test Agent before assigning it in production.
Review roles, scope, and field rules regularly and after a change in team, process, or privacy obligation.
Do not treat a hidden button as a security control: retain server-side authorization and investigate denied attempts through the audit history.

Troubleshooting

The role does not seem to restrict anything: verify that it is assigned to an Agent in the same account and that Granular permissions is enabled.
The person can open a route but an action is unavailable: check the action-specific key; page access does not automatically grant delete, export, or administrative operations.
The person sees unexpected data: review the scope type, selected teams/inboxes, and the conversation or contact relationships. Global settings without a relationship use L1 only.
The phone is masked but the call button still works: also intentional. The call is placed by the system from the contact record, without the number ever being shown to the agent — the rule exists to stop the data being read and copied, not to stop the work.
A field somebody could edit yesterday is now read-only: the rule is now enforced in the interface too. Before, the field looked editable and the save was refused by the server; now it shows as locked from the start. If that person genuinely needs to edit it, change the field rule to Visible.
A masked value cannot be edited: this is intentional. Change the rule to Visible, update the value, and restore the rule.
I cannot delete a role: it is still assigned. Replace those assignments first.
I opened /settings/custom-roles and landed on Roles & Access: that is the expected behavior. In this installation the old address redirects to Roles & Access; there is no Custom Roles screen in the dashboard any more. The custom_roles API still exists and is refused with 401 while the feature is off — even for an Administrator.
I assigned a custom role and the agent still doesn't have it: with the feature off the assignment is discarded without an error. Confirm the feature or use a native role.
I need to remove an old custom role and the account lost the feature: clearing the assignment is still allowed with the feature off — send an empty value.