> ## Documentation Index
> Fetch the complete documentation index at: https://support.entegrata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Roles and permissions

> Control what each user can see and do in the Admin Portal with roles, feature permissions, and record-level scopes.

Entegrata uses role-based app permissions to control what each user can do in the Admin Portal. Permissions live on **roles**. You give a user access by assigning one or more roles to them.

Use roles and permissions when you need to:

* Give some users read-only access while others can make changes
* Limit who can manage users, roles, access control, or instance settings
* Restrict a user to specific data connections or pipelines
* Separate who can change production pipelines from who can change dev pipelines

> [!NOTE]
>
> App permissions control what users can do in the Admin Portal. They don't control which rows of data users can see in your Lakehouse. For data-level security, see [Access Control](/data/access_control/summary.md).

## How permissions work

### Features and permission types

Each area of the Admin Portal is a **feature**, such as data connections, data pipelines, access control, instance settings, users, and roles. A role grants any combination of these permission types on each feature:

| Permission | What it allows |
| - | - |
| **Access** | See and open the area in the Admin Portal |
| **Create** | Add new items, such as a connection, pipeline, or role |
| **Read** | View items and their details |
| **Update** | Edit existing items |
| **Delete** | Remove items |

Not every feature supports every permission type. The permission matrix only shows the types that apply to each feature. See the [feature reference](#feature-reference) for the full list.

### Feature groups

Features are organized into groups: **Admin App**, **Application Permissions**, **Data Connections**, **Data Pipelines**, **Instance Settings**, and **Access Control**. Each group has a top-level feature that controls access to the whole group, and the features inside it control specific areas.

* **Admin App Access** controls whether the user can sign in to the Admin Portal at all. Without it, every other permission is ignored.
* Each group's top-level feature, such as **Data Connections**, controls whether the user can open that part of the Admin Portal.

The permission matrix keeps these levels consistent for you. See [Use the permission matrix](#use-the-permission-matrix).

### Roles are additive

A user's **effective permissions** are the combination of every role assigned to them. If any assigned role grants a permission, the user has it. Removing a permission from one role does not take it away if another assigned role still grants it.

### System and custom roles

* **System roles** are provided by Entegrata and are read-only. You can view and duplicate them, but you can't edit or delete them.
* **Custom roles** are roles you create. You can edit and delete them.

Entegrata provides three system roles:

| Role | What it grants |
| - | - |
| **Administrator** | Every permission on every feature |
| **Editor** | Create, read, and update on most features, but not delete |
| **Viewer** | Read-only access to every feature |

All three roles can sign in to the Admin Portal. See the [feature reference](#feature-reference) for the exact permissions each role grants.

New users get the **Viewer** system role when you don't choose a role during creation.

### Record-level scope

Some features support record-level scope: **Manage Data Connections**, **Manage Production Pipelines**, and **Manage Dev Pipelines**. In a role, the permissions on these features apply either to:

* **All Records**: every connection or pipeline in the instance, including ones created later
* **Specific records**: only the connections or pipelines you add to the role

Record scope is part of the role, not the assignment. When you assign a role to a user, it applies across the instance. To limit a user to specific connections or pipelines, assign a role whose record scope lists those records.

A record-scoped connection grant also covers actions on that connection, such as triggering collections and emitters.

### Production and dev pipelines

Pipeline permissions are split into two features:

* **Manage Production Pipelines** governs production pipelines.
* **Manage Dev Pipelines** governs development and test pipelines.

The `main` pipeline is always governed by production pipeline permissions. A user with only dev pipeline permissions can't edit, diff, or sync `main`.

### When changes take effect

Permissions are cached in the user's browser session for up to one minute. When you change a role or a user's role assignments, the affected user sees the change within about a minute. They may need to reload the page.

## Open the permissions pages

1. In the Admin Portal sidebar, click **Users**.
2. Use the breadcrumb at the top of the page to switch between the **Users** and **Roles** views.

![Users view showing each user and their assigned roles](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/permissions-users-list.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=067a3607a050fd7bec543f67f5ca7150)

> [!NOTE]
>
> To open these pages, a role must grant you **Access** on **Application Permissions**. You also need **Read** on **Manage Users** to see the **Users** view, and **Read** on **Manage Roles** to see the **Roles** view. Views you can't access don't appear in the breadcrumb.

## Manage roles

### View roles

The **Roles** view lists each role's name, description, and type (**System · read-only** or **Custom**). Click a row to open the role. Use the ⋮ menu on a row to **Edit** (or **View** for system roles), **Duplicate**, or **Delete** a role.

![Roles view listing system and custom roles](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/roles-list.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=df38edb063c574c51ca18a4c2f92d722)

### Create a role

1. On the **Roles** view, click **Create Role**.

2. Enter a **Role Name** and an optional **Description**. The name must contain at least one letter or number.

3. Optional: click **Copy from existing role** and choose a role to start from its permissions. This copies the permissions only, not the name or description.

4. In the **Permission Matrix**, select the permissions to grant for each feature. See [Use the permission matrix](#use-the-permission-matrix).

5. For record-scoped features, set the **Record Scope**:

   * Leave **All Records** selected to grant the permissions on every record.
   * Clear **All Records**, then use **Search and add a record...** to choose specific connections or pipelines.

   ![Record Scope limited to a single connection](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/role-record-scope.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=87dbe7f50c771690cf45d302ccebe536)

6. Click **Create Role**.

To create a role based on an existing one, choose **Duplicate** from the role's ⋮ menu. The new role form opens with the name **Copy of** followed by the source role's name, plus the source role's description and permissions.

### Edit a role

To edit a custom role, click its row or choose **Edit** from the ⋮ menu. Update the name, description, or permission matrix, then click **Save Changes**. Changes apply to every user assigned the role.

System roles open read-only with the banner **System role · read-only**. Duplicate a system role to create a custom version you can edit.

![Viewer system role open in read-only mode](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/role-system-readonly.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=68de16de7aa672b4fbb2f35a8db16fbd)

### Delete a role

1. Choose **Delete** from the custom role's ⋮ menu.
2. In the **Delete Role** dialog, click **Delete Role**.

Users assigned the role lose the permissions it granted. This action can't be undone. System roles can't be deleted.

## Use the permission matrix

The **Permission Matrix** lists one row for each feature group, with the group's features nested below it. Each row shows how many of the feature's permissions are granted, such as **3/4 permissions granted**. Hover over the count to see which ones.

Click a row to expand it and select permissions with the checkboxes. Only the permission types the feature supports are shown.

![Role editor with the Manage Data Connections row expanded in the permission matrix](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/role-editor-matrix.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=1f2308692f563a10d64f8552a4a2af35)

The matrix keeps group and feature permissions consistent:

* **Granting a feature permission turns on Access for its group and for Admin App Access.** For example, granting **Read** on **Manage Firewall Rules** also grants **Access** on **Instance Settings** and **Admin App Access**.
* **Removing Access from a group clears every feature in that group.** Removing **Access** from **Admin App Access** clears every feature in the role.
* **Turning Access back on restores what was cleared.** If you remove a group's **Access** by mistake, check it again to restore the previous selections.

To grant everything in a group at once, click **Enable all** on the group's row.

## Assign roles to users

A user can have one or more roles. Each assignment applies across the instance.

### During user creation

When you create a user, select one or more roles in the **Roles** field. If you leave the field empty, the user gets the default **Viewer** role. See [User management](/administration/user/user-management.md#creating-users).

![New User form with the Roles field](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/new-user-roles.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=03314f9e380fd1fec7f44b83837eaf4e)

### On an existing user

1. Open the **Users** view and click the user.
2. In the breadcrumb, switch from **Basic Details** to **Permissions**.
3. Click **Assign Role**.
4. Select a role and click **Assign Role**.

![Assign Role dialog](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/assign-role-dialog.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=33f0a2ef5de6687c4b74e23ff76b0767)

### Revoke a role

The **Assigned Roles** section on the user's **Permissions** tab lists the user's roles. Click the **Revoke role** icon on a role card to remove it.

You can't revoke a user's last remaining role. Assign another role first, or delete the user.

## View a user's effective permissions

![User Permissions tab showing assigned roles and effective permissions](https://mintcdn.com/entegrata/YLoDfUMPPQ1X0E-O/administration/user/images/user-permissions-tab.png?fit=max\&auto=format\&n=YLoDfUMPPQ1X0E-O\&q=85\&s=c5ed53e820d9523275812cda225dea19)

The **Effective Permissions** matrix on a user's **Permissions** tab shows everything the user can do across all of their assigned roles. Expand a feature to see the granted permissions and, for record-scoped features, the specific records the user can access.

## Edit a user's permissions as a new role

You can adjust a single user's access directly from their **Permissions** tab. Because permissions live on roles, your changes are saved as a new role.

> [!NOTE]
>
> This requires **Create** on **Manage Roles** and **Update** on **Manage Users**.

1. On the user's **Permissions** tab, click **Edit permissions**.
2. Change permissions and record scopes in the matrix.
3. Click **Save as new role**.
4. Enter a **Role Name** and optional **Description**. Role names must be unique.
5. Click **Create and replace** (or **Create and assign** if the user has no roles).

Entegrata creates the new role, assigns it to the user, and removes the user's previous roles. The replaced roles stay in the roles list for other users. If assigning the new role fails, the new role is discarded and the user keeps their existing roles.

## Restricted actions

When you don't have permission for an action, the Admin Portal either hides it or shows it disabled:

* **Hidden**: the button, menu item, or sidebar entry doesn't appear. For example, **Create Role** doesn't appear without **Create** on **Manage Roles**.
* **Disabled**: the button stays visible but grayed out. Hover over it to see a **You don't have access** tooltip.

If you open a page you can't access, the Admin Portal shows **Access Denied** with the message "You don't have permission to access this page." If you open a connection or pipeline outside your record scope, the page shows as not found. If a save or other action is denied, you see a message such as "You don't have permission to create pipelines."

Ask an administrator to assign you a role that grants the permission you need. See [Troubleshooting](/administration/user/troubleshooting.md#permission-issues).

## Feature reference

The table lists every feature in the permission matrix, the permission types it supports, and what each system role grants. **C**, **R**, **U**, and **D** stand for Create, Read, Update, and Delete.

Some permissions only work together with another permission. See [Permission dependencies](/administration/user/permission-dependencies.md) before you build a custom role.

Each group's top-level feature (**Admin App Access**, **Application Permissions**, **Data Connections**, **Data Pipelines**, **Instance Settings**, and **Access Control**) supports **Access** only, and all three system roles grant it.

| Group | Feature | Supports | Record scope | Administrator | Editor | Viewer |
| - | - | - | - | - | - | - |
| Application Permissions | Manage Users | C R U D | No | C R U D | C R U | R |
| Application Permissions | Manage Roles | C R U D | No | C R U D | C R U | R |
| Data Connections | Manage Data Connections | C R U D | Yes | C R U D | C R U | R |
| Data Connections | Manage Data Connection Settings | R U | No | R U | R U | R |
| Data Connections | Manage Data Connection Resources | R U | No | R U | R U | R |
| Data Pipelines | Manage Production Pipelines | C R U D | Yes | C R U D | C R U | R |
| Data Pipelines | Manage Dev Pipelines | C R U D | Yes | C R U D | C R U | R |
| Data Pipelines | Manage Silver Entities | C R U D | No | C R U D | C R U | R |
| Data Pipelines | Manage Gold Entities | C R U D | No | C R U D | C R U | R |
| Data Pipelines | Manage Metrics | C R U D | No | C R U D | C R U | R |
| Data Pipelines | Manage Custom Catalog Queries | C R U D | No | C R U D | C R U | R |
| Instance Settings | Manage System Version | R U | No | R U | R U | R |
| Instance Settings | Manage System Network Connection | C R U D | No | C R U D | C R U | R |
| Instance Settings | Manage Firewall Rules | C R U D | No | C R U D | C R U | R |
| Instance Settings | Manage Customer Managed Keys | R U | No | R U | R U | R |
| Instance Settings | Manage Databricks IP Access | C R U D | No | C R U D | C R U | R |
| Access Control | Manage Access Control Groups | C R U D | No | C R U D | C R U | R |
| Access Control | Manage Access Control Entity Rules | C R U D | No | C R U D | C R U | R |

## Related documentation

> **[User Management](/administration/user/user-management.md)**
>
> Create, edit, and delete users

> **[Permission dependencies](/administration/user/permission-dependencies.md)**
>
> Permissions that only work together with another permission

> **[Troubleshooting](/administration/user/troubleshooting.md)**
>
> Common issues and solutions for user management


## Related topics

- [Permission dependencies](/administration/user/permission-dependencies.md)
- [Testing Permissions](/data/access_control/testing-permissions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.