## 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

1. Open **Settings → Roles & Access**.
2. Select **New role** or **Create from template**.
3. Enter a name and description, then select only the required permissions.
4. Under **Scope**, choose **Entire account**, **Specific teams**, or **Specific inboxes**. A scoped
   role must contain at least one team/inbox from its own account.
5. Under **Fields**, set Contact and Organization data to **Visible**, **Masked**, or **Hidden**.
6. Save. In **Settings → Agents**, edit an Agent and assign the role.
7. 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.

## See also

- [Account, agents and teams](/hc/ajuda/articles/administration-conta-agentes-equipes-en)
- [Governance & LGPD](/hc/ajuda/articles/administration-governanca-lgpd-en)
- [Audit logs](/hc/ajuda/articles/administration-auditoria-en)
- [Integrations](/hc/ajuda/articles/administration-integracoes-en)